Skip to content

AGENTS.md

Latest commit

 

History

History
136 lines (120 loc) · 7.47 KB

AGENTS.md

File metadata and controls

136 lines (120 loc) · 7.47 KB

PlanExe agent instructions

Scope: repo-level guardrails for PlanExe services and shared packages. Always check the package-level AGENTS.md for file-specific rules (use rg --files -g 'AGENTS.md' if you are unsure).

Repo architecture map

  • database_api: shared SQLAlchemy models for DB-backed services.
  • worker_plan/worker_plan_api: shared API types/helpers (must stay lightweight).
  • worker_plan: FastAPI service that runs the pipeline.
  • frontend_single_user: Gradio UI (local mode).
  • frontend_multi_user: Flask UI (hosted mode) + Postgres.
  • open_dir_server: local host opener (security critical).
  • worker_plan_database: DB-backed worker that polls tasks.
  • mcp_cloud: MCP stdio server + HTTP wrapper; primary cloud deployment, secondary Docker setup for advanced users, tertiary venv workflow for developers; bridges MCP tools to PlanExe DB/worker_plan.
  • mcp_local: local MCP proxy that forwards tool calls to mcp_cloud and downloads artifacts.

Shared contracts

  • Keep worker_plan HTTP endpoints and response shapes backward compatible.
  • Preserve shared SQLAlchemy models in database_api (nullable defaults for new columns).
  • Run directory naming defaults live in worker_plan/worker_plan_api/generate_run_id.py. Current defaults: single-user uses timestamped IDs; multi-user can use UUIDs. Verify in code before changing run-id formats.
  • Keep prompt catalog UUIDs stable when used as defaults; they live in worker_plan/worker_plan_api/prompt/data/*.jsonl.

Hard rules (agent safety)

  • Never commit directly to main. Always create a feature branch (e.g. feat/short-description, fix/short-description) and commit there. Push the branch and open a PR so CI can verify the changes.
  • Do not add real API keys or passwords to .env, .env.*, or any llm_config/*.json file.
  • Treat track_activity.jsonl as sensitive (may contain API keys/tokens). Never expose it to end users. Store track_activity.jsonl in PlanItem.run_track_activity_jsonl and keep it out of downloadable zips at artifact creation time. Legacy snapshots may be sanitized at download time, but new snapshots should be served directly without unzip/recompress.
  • Do not change run-dir validation or path-allowlist logic in open_dir_server/app.py unless explicitly instructed.
  • Shared packages (database_api, worker_plan_api) must not import service apps (frontend_*, worker_plan_database, open_dir_server, worker_plan.app).
  • If a service needs shared logic, move it into a shared package rather than importing across service boundaries.

Environment variables

  • Canonical env keys live in .env.docker-example, .env.developer-example, and worker_plan/worker_plan_api/planexe_dotenv.py. Read those before adding or renaming env vars.

Cross-service conventions

  • .env and the llm_config/ directory are expected in the repo root for Docker setups.
  • Profile file mapping:
    • baseline -> llm_config/baseline.json
    • premium -> llm_config/premium.json
    • frontier -> llm_config/frontier.json
    • custom -> llm_config/custom.json (or PLANEXE_LLM_CONFIG_CUSTOM_FILENAME)
  • PLANEXE_MODEL_PROFILE selects which profile file is used at runtime.
  • Baseline is the default profile and fallback if another selected profile file is missing.
  • Use PLANEXE_* env vars; prefer existing defaults when adding new ones.
  • Do not assume ports; read docker-compose.yml or the service env defaults (PLANEXE_*_PORT) before any manual verification.

Docker notes

  • PLANEXE_POSTGRES_PORT changes the host port mapping only; containers still connect to Postgres on 5432.
  • The Open Output Dir button requires the host open_dir_server and PLANEXE_OPEN_DIR_SERVER_URL (OS-specific URLs live in docs/docker.md).
  • Keep PLANEXE_HOST_RUN_DIR consistent with run dir mounts so outputs land in the expected host folder.

Documentation sync

  • When changing Docker services, env defaults, or port mappings, update docker-compose.yml, docker-compose.md, and docs/docker.md together.
  • When changing single-user quickstart or LLM env requirements (e.g. OPENROUTER_API_KEY), update docs/getting_started.md.
  • When changing local dev startup steps or the test command, update docs/install_developer.md.
  • For README links, prefer absolute https://docs.planexe.org/... URLs so GitHub readers land on the published docs site.

Testing strategy

  • Prefer unit tests over manual curl/server checks.
  • Run python test.py from repo root for existing coverage.
  • If you change logic without tests, add a unit test close to the code.
  • Do not start services or run curl checks unless explicitly requested.

Coding standards

  • Type hints: add to all public function signatures.
  • Async/sync: FastAPI code can be async; Flask routes must stay sync.
  • Error handling: do not use bare except:; log stack traces.
  • Logging: use logging (avoid print() in service code).
  • Formatting/linting: no repo-wide formatter is configured; follow existing file style and do not add new lint tools unless requested.

LLM structured-output schemas (Literal vs Enum)

  • In Pydantic models used for LLM structured output, use Literal["a", "b"] instead of an Enum type for field annotations.
  • Reason: Enum fields cause model_json_schema() to emit $defs/$ref indirection. Some structured-output backends (e.g. MLX Outlines for local inference) cannot resolve $defs/$ref and fail silently or error out. Literal produces a flat schema with an inline enum array, which is universally supported.
  • Keep the canonical str(Enum) class in the same module as the single source of truth for valid values; the Literal duplicates those values in the schema annotation only.
  • A CI parity test (test_enum_literal_parity.py) asserts that every Literal field stays in sync with its corresponding Enum. If you add or rename an Enum member, update the matching Literal and vice versa.

Python version

  • Canonical version is defined in each package pyproject.toml.

Dependencies

  • worker_plan and frontend_multi_user: add deps in their pyproject.toml.
  • frontend_single_user and worker_plan_database: add deps in requirements.txt.
  • Do not pip install ad-hoc without recording the dependency in the package manifest.

Strategic Alignment (The PlanExe Mindset)

We are evolving from a "Plan Generator" (rough drafts) to a "Plan Execution Engine" (enterprise-grade). New features and proposals should align with this shift:

  1. Trust & Rigor: AI output is untrusted by default.
    • Favor features that verify, cite, and stress-test claims (e.g., Evidence Ledgers, Monte Carlo sims).
    • Avoid features that just "generate more text" without validation.
  2. Execution Focus: A plan is a living tool, not a static PDF.
    • Favor features that monitor reality vs. plan (e.g., drift monitors, readiness gates).
    • Ensure data structures support dynamic updates (databases over documents).
  3. Scale: We are building for users who manage 100+ plans.
    • Favor features that automate sorting, ranking, and routing (e.g., Elo ranking, automated dispatch).

Ecosystem & OpenClaw

PlanExe is designed to be used by both humans and autonomous agents.

  • OpenClaw (an open-source agent framework) is a first-class citizen.
  • We support MCP (Model Context Protocol) to allow bots to natively call PlanExe tools.
  • When designing APIs, assume the caller might be a Raspberry Pi running OpenClaw, not just a human with a browser.