# AGENTS.md

## Role
HERMES-MCP is the central decision engine of the trading subsystem.

It consumes structured inputs (signals, market data, events, sentiment scores) and produces
explicit, actionable trading decisions.

---

## Responsibilities

- aggregate inputs from upstream MCPs
- evaluate strategies
- produce deterministic decision outputs
- act as the single source of truth for strategy selection and intent

---

## Inputs

Expected upstream sources:

- argus-mcp → aggregated signals
- crypto-mcp → market data
- (future) news-mcp → events/news

Inputs must be treated as **read-only** and **trusted but validated**.

---

## Outputs

- decisions → trader-mcp

Decisions must be:
- explicit (no ambiguity)
- complete (no missing fields)
- reproducible (same input → same output, unless explicitly stochastic)

---

## Strict Rules

- MUST NOT execute trades
- MUST NOT access exchanges directly
- MUST NOT fetch raw data from external APIs (use upstream MCPs)

- MUST NOT embed execution logic
- MUST NOT depend on downstream components

- MUST be the ONLY component that activates, deactivates or switches strategies

---

## Decision Model Constraints

- decisions should be stateless where possible
- if state is required, it must be explicit and traceable
- avoid hidden side effects

- log reasoning or signals used for each decision (for auditability)

---

## Interface Stability

Changes to decision format are **breaking changes**.

When modifying:
- update trader-mcp expectations
- ensure backward compatibility or version the schema

---

## Failure Handling

- invalid or missing inputs must not crash the system
- fallback behavior must be explicit (e.g. "no trade")

---

## Development Guidelines

- prefer clarity over cleverness
- keep decision logic modular and testable
- isolate strategy evaluation from data parsing

---

## When Modifying This Repo

Before making changes:

1. Identify all inputs used
2. Identify all outputs affected
3. Check compatibility with trader-mcp
4. Avoid introducing hidden dependencies

---

## Non-Goals

This service is NOT responsible for:
- data collection
- trade execution
- account management