Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (87 loc) · 6.19 KB

AGENTS.md

File metadata and controls

114 lines (87 loc) · 6.19 KB

AxumQuant Codex Workspace Guide

This workspace is large. Default to targeted reads and directory-first navigation.

Token Protocol

  • Do not read whole trees by default.
  • Start with directory listings, then read only the files needed for the current task.
  • Prefer rg --files <dir>, find <dir> -maxdepth N, and focused sed -n over broad repository scans.
  • Read at most 1-3 candidate files first, then narrow further.
  • Do not load archive, build, cache, MCP metadata, or IDE state unless the task explicitly points there.
  • When a task is unclear, inspect root docs first: AGENTS.md, README.md, STACK.md, ARCHITECTURE.md.

Default Skip Zones

Skip these unless the task explicitly requires them:

  • .claude/
  • .cursor/
  • .firecrawl/
  • .git/
  • .venv/
  • **/target/
  • **/__pycache__/
  • **/.pytest_cache/
  • **/dist/
  • **/node_modules/
  • nomad/data/
  • axumQ-app/frontend/dist/
  • axumQ-app/frontend/target/
  • axumQ-app/frontend/target-trunk/
  • axumQ-app/src-tauri/target/
  • data/models/
  • data/training/
  • data/dpo_training/
  • data/dpo_checkpoints/
  • logs/

Read Order

Pick the smallest relevant area first:

  1. Root docs for orientation.
  2. .codex/PROJECT_MAP.md for folder routing.
  3. The nearest service AGENTS.md.
  4. One service subtree.
  5. Specific files inside that subtree.

2026 Efficiency Rules

  • Keep this file short and stable so prompt caching has a better chance to hit.
  • Put detailed policy in .codex/CONTEXT_BUDGET.md and load it only when needed.
  • Use .codex/LIVE_READINESS.md when deciding what to inspect next for production progress.
  • Keep tool usage stable within a task when possible. Avoid changing MCP/tool patterns mid-run.
  • Prefer local shell search for local code. Use MCPs for current docs, external research, or structured extraction.
  • If a new noisy folder appears, add it to .rgignore, .fdignore, and .ignore.

Primary Work Areas

  • src/, tests/, mcp_servers/, alembic/ — Python platform, agents, workflows, MCP servers, tests, and migrations.
  • axum-api-rs/ — Rust API service and MCP-facing handlers.
  • axum-common-rs/ — Shared Rust types and math.
  • axum-execution-engine/ — Rust execution engine and broker logic.
  • axumQ-app/ — Tauri desktop app and frontend.
  • scripts/ — automation, MCP launchers, env tooling.
  • nomad/ — deployment and runtime orchestration.
  • docs/ — focused project docs.

Production Priority

When choosing where to look first, bias toward:

  • Broker execution correctness and reconciliation
  • Risk gates, liquidation controls, and position safety
  • Observability, health checks, and operator control surfaces
  • Deployment readiness, runtime config, and recovery paths
  • Ignore research-heavy or historical data areas unless they directly block live readiness

Architecture Modernization Rule

When touching production, agentic, trading, risk, data, or orchestration code, enforce the current system architecture instead of preserving stale patterns.

  • Purge obsolete code paths when they no longer match the current system. Do not leave dead adapters, deprecated broker/config/model references, duplicate business logic, or unused compatibility shims unless an operator-facing migration window requires them.
  • Redesign deeper business logic using OOP, DDD, modular-monolith boundaries, and abstract base classes or traits where polymorphic behavior is real. Prefer explicit class/service/repository/controller/gateway boundaries over procedural scripts with hidden state.
  • Keep domains business-first: execution, risk, market data, strategy promotion, agent orchestration, observability, deployment, and operator control each own their models, services, ports, adapters, and acceptance tests.
  • Agentic components must depend on stable contracts: typed DTOs, abstract ports, idempotent services, bounded retries/timeouts, fail-closed risk gates, audit events, and deterministic recovery paths.
  • "Neuro-Graphic Architecture" means agent decisions, market context, strategy lineage, risk state, and operator actions must be modeled as typed domain objects and graph/event relationships where useful; do not replace critical trading controls with opaque LLM prompts.
  • A refactor is incomplete until old code is removed or explicitly quarantined, imports/routes/jobs/tests are updated, and verification proves the live path still works.
  • Do not claim code is impossible to break. Engineer for high resilience: strong invariants, contract tests, property/fuzz tests where relevant, health checks, observability, rollback paths, and kill switches.

Routing Hints

  • API bug: start in axum-api-rs/src/ or src/api/.
  • Desktop/Tauri issue: start in axumQ-app/src-tauri/src/ or axumQ-app/frontend/src/.
  • Strategy/agent/research issue: start in src/agents/, src/factory/, src/research/, or src/island/.
  • MCP issue: start in scripts/mcp/, .mcp.json, mcp_servers/, or axum-api-rs/src/mcp/.
  • Infra/runtime issue: start in nomad/, docker/, or service Dockerfiles.

Search Discipline

  • Use scoped searches such as rg "symbol" src axum-api-rs/src.
  • Avoid rg from repo root unless the pattern is highly specific.
  • Use rg --files before content search when the folder is not obvious.
  • Use .codex/PROJECT_MAP.md instead of recursively listing large subtrees.

Learned User Preferences

  • When executing an attached implementation plan, do not edit the plan file; drive the existing todo list from in progress through completed without recreating duplicate todos.

Learned Workspace Facts

  • Prefer 127.0.0.1:8013 for local axum-api-rs health checks, curl runbooks, and AxumQ gateway alignment so tooling matches common binds and avoids localhost IPv4/IPv6 ambiguity.
  • If AxumQ shows OFFLINE, partial bundles, or persistently empty page data while the gateway responds, verify the desktop AXUMQ_API_TOKEN matches system_settings.security.gateway_bearer (see scripts/axum_gateway_bearer_resolve.py, scripts/gateway_bearer_push_and_sync.py, and Settings wiring summary docs).
  • Before Nomad stack bring-up or jobs that use private images or schema migration, export Docker Hub credentials or source scripts/inject-secrets.sh from the repo root so pulls and migrate steps do not abort mid-run.