# Binance Event Contract Agent Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Build a modular-monolith quantitative agent platform for Binance event contracts with multi-agent dry-run, backtesting, self-optimization, OpenAI-compatible model switching, and a React monitoring/confirmation console.

**Architecture:** Use a single repository with a backend app, React frontend, shared persistence, and deepagents-based orchestration. Keep execution control in explicit system state machines while agents act only as structured proposers whose outputs are validated, persisted, replayed, and compared.

**Tech Stack:** TypeScript, Node.js, React, deepagents, PostgreSQL, Redis, WebSocket, OpenAI-compatible SDK/client, Vitest, Playwright

---

### Task 1: Initialize repository and workspace structure

**Files:**
- Create: `package.json`
- Create: `pnpm-workspace.yaml`
- Create: `tsconfig.base.json`
- Create: `.gitignore`
- Create: `apps/api/package.json`
- Create: `apps/web/package.json`
- Create: `packages/shared/package.json`
- Create: `packages/agent-runtime/package.json`
- Create: `packages/strategy-lab/package.json`
- Create: `packages/market-data/package.json`
- Create: `packages/execution-ledger/package.json`
- Create: `docs/architecture/README.md`

**Step 1: Write the failing workspace smoke test**

Create a simple test in `packages/shared` that imports a constant from another package path that does not exist yet.

**Step 2: Run test to verify it fails**

Run: `pnpm test --filter shared`
Expected: FAIL because the workspace package export is missing.

**Step 3: Write minimal workspace scaffolding**

Create the monorepo package manifests, base TypeScript config, and initial package exports so the smoke test can resolve imports.

**Step 4: Run test to verify it passes**

Run: `pnpm test --filter shared`
Expected: PASS

**Step 5: Commit**

```bash
git add .
git commit -m "chore: initialize workspace structure"
```

### Task 2: Create shared domain schemas and enums

**Files:**
- Create: `packages/shared/src/domain/strategy.ts`
- Create: `packages/shared/src/domain/experiment.ts`
- Create: `packages/shared/src/domain/model-profile.ts`
- Create: `packages/shared/src/domain/trade.ts`
- Create: `packages/shared/src/domain/market.ts`
- Create: `packages/shared/src/index.ts`
- Test: `packages/shared/src/domain/strategy.test.ts`

**Step 1: Write the failing test**

Write tests that assert strategy states, model profile parsing, and dry-run trade records conform to explicit schemas.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/shared/src/domain/strategy.test.ts`
Expected: FAIL because the schemas and enums do not exist.

**Step 3: Write minimal implementation**

Create versioned domain types and validation schemas for:

- strategy lifecycle states
- model profiles
- market snapshots
- dry-run/live trade proposals
- experiment results

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/shared/src/domain/strategy.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/shared
git commit -m "feat: add shared domain schemas"
```

### Task 3: Build configuration loading and model profile registry

**Files:**
- Create: `apps/api/src/config/env.ts`
- Create: `apps/api/src/config/model-profile-registry.ts`
- Create: `apps/api/src/config/config.test.ts`
- Modify: `packages/shared/src/domain/model-profile.ts`

**Step 1: Write the failing test**

Write tests that load sample OpenAI-compatible profiles and assert agent bindings resolve correctly.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest apps/api/src/config/config.test.ts`
Expected: FAIL because the registry and loader do not exist.

**Step 3: Write minimal implementation**

Implement:

- env loading
- model profile parsing
- profile lookup by name
- agent-to-profile binding resolution

**Step 4: Run test to verify it passes**

Run: `pnpm vitest apps/api/src/config/config.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add apps/api/src/config packages/shared/src/domain/model-profile.ts
git commit -m "feat: add model profile registry"
```

### Task 4: Implement market data ingestion interfaces and normalized snapshot storage

**Files:**
- Create: `packages/market-data/src/provider/binance.ts`
- Create: `packages/market-data/src/service/normalizer.ts`
- Create: `packages/market-data/src/service/market-store.ts`
- Create: `packages/market-data/src/index.ts`
- Test: `packages/market-data/src/service/normalizer.test.ts`

**Step 1: Write the failing test**

Write tests that feed raw market payloads and assert normalized snapshots are created with timestamps and versioned identifiers.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/market-data/src/service/normalizer.test.ts`
Expected: FAIL because normalization/storage code does not exist.

**Step 3: Write minimal implementation**

Implement:

- Binance market data adapter interface
- normalized snapshot builder
- in-memory repository abstraction for snapshots

Keep transport and persistence separated.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/market-data/src/service/normalizer.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/market-data
git commit -m "feat: add market snapshot normalization"
```

### Task 5: Create execution ledger primitives for simulated and proposed live trades

**Files:**
- Create: `packages/execution-ledger/src/service/trade-ledger.ts`
- Create: `packages/execution-ledger/src/service/state-machine.ts`
- Create: `packages/execution-ledger/src/index.ts`
- Test: `packages/execution-ledger/src/service/trade-ledger.test.ts`

**Step 1: Write the failing test**

Write tests covering:

- dry-run trade creation
- settlement updates
- live proposal creation
- manual confirm/reject transitions

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/execution-ledger/src/service/trade-ledger.test.ts`
Expected: FAIL because the ledger/state machine does not exist.

**Step 3: Write minimal implementation**

Implement trade lifecycle handling with explicit state transitions and audit timestamps.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/execution-ledger/src/service/trade-ledger.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/execution-ledger
git commit -m "feat: add execution ledger state machine"
```

### Task 6: Create agent runtime contracts and structured-output adapters

**Files:**
- Create: `packages/agent-runtime/src/contracts/agent-task.ts`
- Create: `packages/agent-runtime/src/contracts/agent-output.ts`
- Create: `packages/agent-runtime/src/runtime/orchestrator.ts`
- Create: `packages/agent-runtime/src/runtime/output-validator.ts`
- Create: `packages/agent-runtime/src/index.ts`
- Test: `packages/agent-runtime/src/runtime/output-validator.test.ts`

**Step 1: Write the failing test**

Write tests that assert malformed agent responses are rejected and valid structured responses are accepted.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/agent-runtime/src/runtime/output-validator.test.ts`
Expected: FAIL because runtime contracts and validation do not exist.

**Step 3: Write minimal implementation**

Define agent task payloads and implement structured output validation around deepagents integration boundaries.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/agent-runtime/src/runtime/output-validator.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/agent-runtime
git commit -m "feat: add agent runtime contracts"
```

### Task 7: Implement first-pass agent roles

**Files:**
- Create: `packages/agent-runtime/src/agents/orchestrator-agent.ts`
- Create: `packages/agent-runtime/src/agents/signal-agent.ts`
- Create: `packages/agent-runtime/src/agents/risk-agent.ts`
- Create: `packages/agent-runtime/src/agents/evaluator-agent.ts`
- Create: `packages/agent-runtime/src/agents/optimizer-agent.ts`
- Test: `packages/agent-runtime/src/agents/signal-agent.test.ts`

**Step 1: Write the failing test**

Write tests for:

- signal agent structured output shape
- risk agent skip decisions
- optimizer proposal schema

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/agent-runtime/src/agents/signal-agent.test.ts`
Expected: FAIL because agent role implementations do not exist.

**Step 3: Write minimal implementation**

Implement lightweight role wrappers that:

- prepare prompts/messages
- call the model profile client
- validate structured output
- return domain-safe results

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/agent-runtime/src/agents/signal-agent.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/agent-runtime/src/agents
git commit -m "feat: add core agent roles"
```

### Task 8: Build strategy registry and lifecycle state handling

**Files:**
- Create: `packages/strategy-lab/src/registry/strategy-registry.ts`
- Create: `packages/strategy-lab/src/service/strategy-state-service.ts`
- Create: `packages/strategy-lab/src/index.ts`
- Test: `packages/strategy-lab/src/registry/strategy-registry.test.ts`

**Step 1: Write the failing test**

Write tests for:

- strategy version creation
- state transitions
- immutable result history

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/strategy-lab/src/registry/strategy-registry.test.ts`
Expected: FAIL because registry/state handling does not exist.

**Step 3: Write minimal implementation**

Implement versioned strategy registration and lifecycle transitions for `draft`, `candidate`, `dry-run`, `approved-for-live`, and `archived`.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/strategy-lab/src/registry/strategy-registry.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/strategy-lab
git commit -m "feat: add strategy registry lifecycle"
```

### Task 9: Implement dry-run engine for parallel strategy evaluation

**Files:**
- Create: `packages/strategy-lab/src/dry-run/dry-run-engine.ts`
- Create: `packages/strategy-lab/src/dry-run/dry-run-scheduler.ts`
- Test: `packages/strategy-lab/src/dry-run/dry-run-engine.test.ts`
- Modify: `packages/agent-runtime/src/runtime/orchestrator.ts`
- Modify: `packages/execution-ledger/src/service/trade-ledger.ts`

**Step 1: Write the failing test**

Write tests that run multiple strategy definitions against the same market snapshot and assert isolated simulated trades are produced.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/strategy-lab/src/dry-run/dry-run-engine.test.ts`
Expected: FAIL because the dry-run engine does not exist.

**Step 3: Write minimal implementation**

Implement the dry-run pipeline:

- snapshot intake
- signal evaluation
- risk filtering
- simulated order write

Ensure each strategy instance is isolated and parallel-safe.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/strategy-lab/src/dry-run/dry-run-engine.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/strategy-lab packages/agent-runtime/src/runtime/orchestrator.ts packages/execution-ledger/src/service/trade-ledger.ts
git commit -m "feat: add parallel dry-run engine"
```

### Task 10: Implement historical replay and backtest runner

**Files:**
- Create: `packages/strategy-lab/src/backtest/replay-runner.ts`
- Create: `packages/strategy-lab/src/backtest/backtest-runner.ts`
- Create: `packages/strategy-lab/src/backtest/windowing.ts`
- Test: `packages/strategy-lab/src/backtest/backtest-runner.test.ts`

**Step 1: Write the failing test**

Write tests that replay a fixed sequence of market snapshots and assert repeatable outcomes for a test strategy.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/strategy-lab/src/backtest/backtest-runner.test.ts`
Expected: FAIL because the replay/backtest runner does not exist.

**Step 3: Write minimal implementation**

Implement deterministic replay with explicit training, validation, and forward windows.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/strategy-lab/src/backtest/backtest-runner.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/strategy-lab/src/backtest
git commit -m "feat: add backtest replay runner"
```

### Task 11: Implement scoring and baseline comparison

**Files:**
- Create: `packages/strategy-lab/src/scoring/risk-adjusted-score.ts`
- Create: `packages/strategy-lab/src/scoring/baselines.ts`
- Test: `packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts`

**Step 1: Write the failing test**

Write tests that assert:

- drawdown penalizes score
- higher stability improves score
- candidate strategies are compared against random, momentum, and mean-reversion baselines

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts`
Expected: FAIL because scoring and baselines do not exist.

**Step 3: Write minimal implementation**

Implement the risk-adjusted score and baseline evaluators.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/strategy-lab/src/scoring
git commit -m "feat: add strategy scoring and baselines"
```

### Task 12: Implement experiment store and optimizer feedback loop

**Files:**
- Create: `packages/strategy-lab/src/experiments/experiment-store.ts`
- Create: `packages/strategy-lab/src/experiments/optimizer-loop.ts`
- Test: `packages/strategy-lab/src/experiments/optimizer-loop.test.ts`
- Modify: `packages/agent-runtime/src/agents/evaluator-agent.ts`
- Modify: `packages/agent-runtime/src/agents/optimizer-agent.ts`

**Step 1: Write the failing test**

Write tests that verify evaluator summaries can produce optimizer proposals which enqueue backtest candidates without changing live state.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest packages/strategy-lab/src/experiments/optimizer-loop.test.ts`
Expected: FAIL because the loop/store do not exist.

**Step 3: Write minimal implementation**

Implement:

- experiment persistence
- evaluator summary ingestion
- optimizer proposal creation
- candidate queueing for backtest

**Step 4: Run test to verify it passes**

Run: `pnpm vitest packages/strategy-lab/src/experiments/optimizer-loop.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add packages/strategy-lab/src/experiments packages/agent-runtime/src/agents/evaluator-agent.ts packages/agent-runtime/src/agents/optimizer-agent.ts
git commit -m "feat: add optimizer feedback loop"
```

### Task 13: Build backend app shell with HTTP and WebSocket APIs

**Files:**
- Create: `apps/api/src/server.ts`
- Create: `apps/api/src/routes/strategies.ts`
- Create: `apps/api/src/routes/experiments.ts`
- Create: `apps/api/src/routes/models.ts`
- Create: `apps/api/src/routes/live-confirm.ts`
- Create: `apps/api/src/ws/events.ts`
- Test: `apps/api/src/server.test.ts`

**Step 1: Write the failing test**

Write tests that assert the API exposes strategy, experiment, model, and live-confirm endpoints and emits socket events for updates.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest apps/api/src/server.test.ts`
Expected: FAIL because the server and routes do not exist.

**Step 3: Write minimal implementation**

Implement the backend shell with:

- route registration
- in-process service wiring
- WebSocket event publishing

**Step 4: Run test to verify it passes**

Run: `pnpm vitest apps/api/src/server.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add apps/api
git commit -m "feat: add backend api shell"
```

### Task 14: Build React console shell and live dashboards

**Files:**
- Create: `apps/web/src/app/router.tsx`
- Create: `apps/web/src/pages/dashboard.tsx`
- Create: `apps/web/src/pages/strategies.tsx`
- Create: `apps/web/src/pages/experiments.tsx`
- Create: `apps/web/src/pages/live-confirm.tsx`
- Create: `apps/web/src/pages/models-config.tsx`
- Create: `apps/web/src/lib/api.ts`
- Create: `apps/web/src/lib/socket.ts`
- Test: `apps/web/src/pages/dashboard.test.tsx`

**Step 1: Write the failing test**

Write tests that assert each core page renders expected panels from mocked API/WebSocket data.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest apps/web/src/pages/dashboard.test.tsx`
Expected: FAIL because the UI shell does not exist.

**Step 3: Write minimal implementation**

Implement a simple but usable React console with the five approved views.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest apps/web/src/pages/dashboard.test.tsx`
Expected: PASS

**Step 5: Commit**

```bash
git add apps/web
git commit -m "feat: add monitoring console shell"
```

### Task 15: Add manual live-confirm workflow end to end

**Files:**
- Modify: `apps/api/src/routes/live-confirm.ts`
- Modify: `packages/execution-ledger/src/service/state-machine.ts`
- Modify: `apps/web/src/pages/live-confirm.tsx`
- Test: `apps/api/src/live-confirm-flow.test.ts`

**Step 1: Write the failing test**

Write an integration test that creates a live proposal, confirms it, and rejects another proposal with audit metadata.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest apps/api/src/live-confirm-flow.test.ts`
Expected: FAIL because the full flow is incomplete.

**Step 3: Write minimal implementation**

Implement explicit confirm/reject endpoints and UI actions, persisting actor and timestamp metadata.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest apps/api/src/live-confirm-flow.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add apps/api/src/routes/live-confirm.ts packages/execution-ledger/src/service/state-machine.ts apps/web/src/pages/live-confirm.tsx
git commit -m "feat: add manual live confirmation flow"
```

### Task 16: Add persistence adapters for PostgreSQL and Redis

**Files:**
- Create: `apps/api/src/db/schema.sql`
- Create: `apps/api/src/db/repositories/strategy-repository.ts`
- Create: `apps/api/src/db/repositories/experiment-repository.ts`
- Create: `apps/api/src/db/repositories/trade-repository.ts`
- Create: `apps/api/src/cache/redis-client.ts`
- Test: `apps/api/src/db/repositories/strategy-repository.test.ts`

**Step 1: Write the failing test**

Write repository tests using a test database or local containerized database.

**Step 2: Run test to verify it fails**

Run: `pnpm vitest apps/api/src/db/repositories/strategy-repository.test.ts`
Expected: FAIL because persistence adapters do not exist.

**Step 3: Write minimal implementation**

Implement persistence adapters and map domain entities to database records.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest apps/api/src/db/repositories/strategy-repository.test.ts`
Expected: PASS

**Step 5: Commit**

```bash
git add apps/api/src/db apps/api/src/cache
git commit -m "feat: add persistence adapters"
```

### Task 17: Add deterministic replay fixtures and integration coverage

**Files:**
- Create: `tests/fixtures/market/window-10m.json`
- Create: `tests/integration/dry-run-replay.test.ts`
- Create: `tests/integration/backtest-candidate-promotion.test.ts`

**Step 1: Write the failing test**

Write integration tests that:

- replay a fixed 10-minute market sequence through multiple strategies
- assert repeatable results
- assert candidate promotion refuses failing risk-adjusted baselines

**Step 2: Run test to verify it fails**

Run: `pnpm vitest tests/integration`
Expected: FAIL because the end-to-end integration path is incomplete.

**Step 3: Write minimal implementation**

Fill missing wiring required to make deterministic replay and promotion gates pass.

**Step 4: Run test to verify it passes**

Run: `pnpm vitest tests/integration`
Expected: PASS

**Step 5: Commit**

```bash
git add tests
git commit -m "test: add deterministic replay integration coverage"
```

### Task 18: Add local developer experience and deployment packaging

**Files:**
- Create: `docker-compose.yml`
- Create: `.env.example`
- Create: `README.md`
- Create: `scripts/dev.ps1`
- Create: `scripts/test.ps1`
- Create: `scripts/start-local.ps1`

**Step 1: Write the failing test**

Write a smoke-check script or README verification checklist that fails when required env variables or services are missing.

**Step 2: Run test to verify it fails**

Run: `powershell -File scripts/test.ps1`
Expected: FAIL because scripts and packaging do not exist.

**Step 3: Write minimal implementation**

Add:

- local startup instructions
- containerized dependencies
- environment template
- developer scripts

**Step 4: Run test to verify it passes**

Run: `powershell -File scripts/test.ps1`
Expected: PASS

**Step 5: Commit**

```bash
git add docker-compose.yml .env.example README.md scripts
git commit -m "chore: add local dev and deployment packaging"
```

### Task 19: Verify the whole vertical slice

**Files:**
- Modify: `README.md`
- Modify: `docs/architecture/README.md`

**Step 1: Run the focused test suites**

Run:

```bash
pnpm vitest packages/shared packages/market-data packages/execution-ledger packages/agent-runtime packages/strategy-lab
pnpm vitest apps/api apps/web tests/integration
```

Expected: PASS

**Step 2: Run the app smoke start**

Run:

```bash
powershell -File scripts/start-local.ps1
```

Expected: API starts, web starts, database/cache dependencies become reachable.

**Step 3: Verify manual live-confirm flow**

Run the app and manually confirm:

- market data appears
- multiple dry-run strategies render
- experiments show history
- a proposed live trade can be confirmed/rejected

**Step 4: Update docs**

Document:

- how strategy versions move through states
- how model profiles are configured
- how to add a new agent role

**Step 5: Commit**

```bash
git add README.md docs/architecture/README.md
git commit -m "docs: finalize vertical slice verification notes"
```