# AGENTS.md

## Role
TRADER-MCP is a strategy runtime.

It executes multiple independent trading strategies and converts their outputs into execution intents for exec-mcp.

---

## Architecture

TRADER-MCP is structured in three layers:

1. Strategy Layer
   - runs pluggable strategies (grid, mean reversion, etc.)
   - produces trade intents

2. Runtime Layer
   - manages lifecycle of strategies (start/stop/configure)
   - isolates strategies from each other

3. Execution Layer
   - translates intents into exec-mcp commands
   - ensures format correctness

---

## Control Authority

- hermes-mcp controls:
  - which strategies are active
  - strategy parameters
  - global risk posture

- trader-mcp must obey all hermes control signals
- trader-mcp must NOT override or reinterpret them

---

## Core Invariants

- strategies are independent units
- no strategy may access others’ internal state
- trader-mcp does not define market stance
- execution is derived only from strategy outputs + Hermes constraints

---

## Boundary Rules

- NO strategy selection logic (belongs to Hermes)
- NO direct exchange access
- NO market-data-driven decision making outside strategies
- NO cross-strategy coupling

---

## Failure Model

- strategy failures must be isolated
- system must continue running unaffected strategies
- invalid outputs must be rejected, not corrected silently

---

## Local Environment

- before claiming a Python dependency is missing, source the repo-local `.venv`
- prefer running Python, pytest, and helper scripts through the activated `.venv`

---

## Interface Stability

Changes affecting:
- Hermes control signals
- execution intent format

are breaking and must be coordinated across MCPs.