# Codex Exec AI Trader Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a live-only one-shot AI trading command that uses `codex exec` for BUY/SELL/HOLD predictions and routes approved actions through existing risk and execution engines.

**Architecture:** Add a focused `ai_trader.py` module for prediction parsing, Codex subprocess calls, and orchestration. Extend settings, CLI, script, README, and tests without changing existing auto-buy/auto-sell behavior.

**Tech Stack:** Python 3.11, Typer, Pydantic Settings, SQLite storage, pytest, Binance Spot client, local `codex exec` CLI.

---

### Task 1: AI Trader Configuration

**Files:**
- Modify: `src/binance_quant/config.py`
- Modify: `.env.example`
- Test: `tests/test_config.py`

- [ ] Write failing tests for `live_ai_trader_enabled`, `ai_trader_symbols`, `ai_trader_model`, `ai_trader_min_confidence`, and `ai_trader_codex_timeout_seconds` defaults and env overrides.
- [ ] Implement the new settings fields and validators.
- [ ] Run `pytest tests/test_config.py -q` and confirm the new tests pass.

### Task 2: Codex Predictor Adapter

**Files:**
- Create: `src/binance_quant/ai_trader.py`
- Test: `tests/test_ai_trader.py`

- [ ] Write failing tests for parsing valid JSON predictions, rejecting invalid action/confidence/symbol output as HOLD, and constructing a `codex exec` command with optional `--model` and timeout.
- [ ] Implement `AiTradePrediction`, `CodexExecPredictor`, prompt/schema helpers, and defensive parsing.
- [ ] Run `pytest tests/test_ai_trader.py -q` and confirm predictor tests pass.

### Task 3: One-Shot AI Trade Orchestration

**Files:**
- Modify: `src/binance_quant/ai_trader.py`
- Test: `tests/test_ai_trader.py`

- [ ] Write failing tests for disabled/live-mode rejection, HOLD no-op, BUY delegation through auto-buy risk/execution, and SELL delegation through auto-sell risk/execution.
- [ ] Implement `run_live_ai_trade_once(settings, exchange_client=None, predictor=None, now_ms=None)` returning a small execution result with run id, status, symbol, action, and reason.
- [ ] Reuse existing storage reservation and auto-buy/auto-sell execution engines instead of adding model-controlled order submission.
- [ ] Run `pytest tests/test_ai_trader.py -q` and confirm orchestration tests pass.

### Task 4: CLI And Script Exposure

**Files:**
- Modify: `src/binance_quant/cli.py`
- Modify: `scripts/run.ps1`
- Test: `tests/test_cli.py`
- Test: `tests/test_run_script.py`

- [ ] Write failing tests for `binance-quant live-ai-trade-once` output and script action registration/safety guard.
- [ ] Add the Typer command and script action.
- [ ] Run `pytest tests/test_cli.py tests/test_run_script.py -q` and confirm tests pass.

### Task 5: Documentation And Full Verification

**Files:**
- Modify: `README.md`
- Modify: `.env.example`

- [ ] Document `live-ai-trade-once`, configuration keys, and the safety rule that Codex only predicts and local risk engines decide execution.
- [ ] Run `pytest -q` for the full suite.
- [ ] Inspect `git diff --stat` and ensure changes are scoped to AI trader plus requested config updates.