prodex AGENTS.md

AGENTS.md

This file applies to the entire repository. Keep agent guidance actionable and repository-specific; the maintained documents linked below own detailed architecture, policy, threat-model, and test contracts.

Scope and source of truth

When rules conflict, use this order:

1. Current repository behavior and safety invariants.
2. Enforced CI guards, test runners, and package.json scripts.
3. Maintained Prodex documentation: architecture, testing, runtime policy, and threat model.
4. This file.
5. Transferable lessons from upstream Codex guidance.
6. Generic Rust preferences.

Cargo.toml and each crate manifest define workspace membership and dependency ownership. Do not infer a boundary from a directory name alone. Repository prose, comments, examples, fixtures, and new documentation must be in English.

Project summary and ownership

Prodex is a Rust workspace whose CLI wraps Codex and manages isolated CODEX_HOME profiles. It also builds dedicated gateway and control-plane entrypoints. Keep composition roots thin:

• src/main.rs, src/bin/, and src/lib.rs wire entrypoints and compatibility facades.
• prodex-cli owns Clap parsing, help, defaults, and command normalization.
• prodex-app owns CLI command routing, application composition, profile flows, runtime launch, and live orchestration. It must not become the home for reusable domain, storage, rendering, provider, or transport-neutral logic.
• prodex-application owns side-effect-free use-case plans and ports. Concrete transports, providers, and storage adapters belong in composition roots.
• prodex-domain owns pure identifiers, security context, policy, accounting, and governance decisions. It must not depend on HTTP, CLI, database drivers, filesystem/process APIs, providers, or network clients.
• prodex-runtime-proxy owns proxy boundary types, classifiers, affinity/health/admission helpers, compatibility transforms, and bounded transport executors. Keep it hot-path-safe; live launch and app orchestration remain in prodex-app.
• prodex-runtime-* crates own focused runtime policy, state, quota, launch, diagnostics, broker, and provider-runtime boundaries; inspect the owning crate before editing.
• prodex-gateway-core owns HTTP-neutral admission/routing contracts; prodex-gateway-http owns framework-neutral HTTP policy; prodex-gateway-server owns bounded async Hyper/TLS serving. Do not move policy into the server adapter.
• prodex-storage owns adapter-neutral commands and contracts. Driver-free SQL/plans belong in prodex-storage-postgres, prodex-storage-redis, or prodex-storage-sqlite; async or blocking execution belongs in the matching *-runtime adapter. DDL and migrations stay out of request-serving paths.
• prodex-terminal-ui stays generic: terminal dimensions, layout, text, and rendering helpers; app- or runtime-specific report models stay in report crates or prodex-app.