|
|
@@ -0,0 +1,107 @@
|
|
|
+# 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
|
