mzaxd/die
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
709d997e59f68b4411d1f29ff65df3094875b809
die/docs/plans/2026-03-28-binance-event-contract-agent.md
T

22 KiB
Raw Blame History

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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:

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

git add README.md docs/architecture/README.md
git commit -m "docs: finalize vertical slice verification notes"
Reference in New Issue View Git Blame Copy Permalink