Skip to content

AGENTS.md

Latest commit

 

History

History
215 lines (177 loc) · 7.7 KB

AGENTS.md

File metadata and controls

215 lines (177 loc) · 7.7 KB

Development Context - DEXBot2

Branch Strategy

Pipeline: test → dev → main (ONE DIRECTION ONLY!)

  • test: Primary development branch (where work happens)
  • dev: Integration/staging (merged from test)
  • main: Production-ready (merged from dev)

⚠️ KEY RULE: Always merge test → dev, NEVER dev → test ⚠️ KEY RULE: See Absolute Git Action Gate below for all write-action authorization rules. ⚠️ KEY RULE: Default to manual merge/push flow for branch promotion when requested, unless the user specifically asks to use one of the sync scripts.

Absolute Git Action Gate (User-Directed Writes)

Agent must NOT proactively ask for or execute git write actions. The agent only runs git write actions when the user clearly requests them.

Git write actions include:

  • git add
  • git commit
  • git commit --amend
  • git reset (any mode)
  • git rebase
  • git merge
  • git push
  • git tag
  • git checkout / git switch to another branch

Branch-promotion scripts include:

  • npm run ptest
  • npm run pdev
  • npm run pmain

Read-only git commands are always allowed (for example: git status, git diff, git log, git show).

Interpretation rules:

  1. If a user clearly asks for a git write action, execute it.
  2. Short approvals like "yes", "ok", "do it", or "go ahead" are valid confirmation when they clearly refer to the immediately previous proposed action.
  3. If wording is ambiguous, ask one clarifying question before running destructive actions.
  4. git commit --amend is allowed when explicitly requested by the user.
  5. Before a git write action, restate the user authorization in one short line.

See docs/WORKFLOW.md for detailed workflow guide.

Commit Quality Standard

When creating commits, prefer high-context commit messages for non-trivial fixes/features.

  • Subject: concise conventional prefix (fix:, feat:, docs:) with clear scope.
  • Body required for substantial changes: explain why, not only what changed.
  • Structure:
    1. Short problem statement/context
    2. Per-fix sections with file path(s) and behavioral impact
    3. Risk/edge-case notes when relevant
    4. Validation/testing notes (commands or scenario checks)
  • Formatting: use readable markdown headers/bullets in commit body for scanability.
  • CLI formatting safety:
    • Never use /n or literal \\n text as a newline placeholder in commit/PR bodies.
    • Always pass real newlines to Git/GitHub (multi-line body), not escaped newline text.
    • Prefer heredocs for reliability when using git commit and gh pr create.
  • Atomicity: keep unrelated edits out of the commit; document only included changes.

Recommended CLI patterns (newline-safe):

# Commit message with proper markdown/newlines
git commit -F- <<'EOF'
fix: <short summary>

<context>

## <Fix area>
- Problem:
- Impact:
- Solution:

## Testing Notes
- <test command>
EOF

# PR body with proper markdown/newlines
gh pr create --title "<title>" --body-file - <<'EOF'
## Summary
- <item>

## Testing
- <command>
EOF

Recommended template:

fix: <short summary>

<1-2 line context>

## <Fix area 1>
File: <path>
- Problem:
- Impact:
- Solution:

## <Fix area 2>
File: <path>
- Problem:
- Impact:
- Solution:

## Testing Notes
- <test/verification>

Key Files

Entry Points

  • dexbot.js - Main CLI entry point
  • bot.js - Alternative bot starter
  • pm2.js - PM2 process management
  • unlock-start.js - Single-prompt starter (no PM2)
  • credential-daemon.js - Credential daemon

Core Bot

  • modules/dexbot_class.js - Core bot class, lifecycle orchestration, and shared runtime wiring
  • modules/dexbot_fill_runtime.js - Fill processing runtime and replay-safe accounting helpers
  • modules/dexbot_maintenance_runtime.js - Maintenance runtime for sync loops and grid checks
  • modules/constants.js - Centralized configuration and tuning parameters
  • modules/bitshares_client.js - BitShares connection and node management integration
  • modules/node_manager.js - Multi-node health checking and failover
  • modules/general_settings.js - General settings management
  • modules/graceful_shutdown.js - Graceful shutdown handling
  • modules/chain_keys.js - Key management
  • modules/bots_file_lock.js - Bot config file locking
  • modules/btsdex_event_patch.js - BitShares DEX event patching

Order Management (modules/order/)

  • manager.js - Order lifecycle and state management
  • grid.js - Grid calculation, placement, and management
  • working_grid.js - Copy-on-write working grid
  • strategy.js - Trading strategy (anchor & refill, consolidation)
  • accounting.js - Fee accounting and fund tracking
  • sync_engine.js - Blockchain synchronization
  • processed_fill_store.js - Processed fill dedupe persistence and batching
  • startup_reconcile.js - Startup order reconciliation
  • runner.js - Order execution runner
  • async_lock.js - Concurrency control
  • logger.js - Order logging
  • logger_state.js - Logger state tracking
  • format.js - Order formatting
  • export.js - Order data export
  • index.js - Module exports
  • utils/ - Utilities (math, order, system, validate)

Market Adapter (market_adapter/)

  • price_adapter.js - AMA delta threshold, grid price offset persistence, and grid recalculation trigger
  • core/price_adapter_service.js - Price adapter service core (offset calculation, bound clamping)
  • ama_signal_runner.js - AMA signal processing
  • blockchain_source.js - Blockchain data source
  • kibana_source.js - Kibana data source
  • kibana_api.js - Kibana API client
  • native_api.js - Native API client
  • fetch_lp_data.js - Liquidity pool data fetching
  • merge_lp_data.js - LP data merging
  • candle_utils.js - Candlestick utilities
  • lp_chart_core.js - LP chart core logic
  • chart_lp_prices.js - LP price charting

Blockchain Interaction

  • modules/chain_orders.js - Blockchain order operations
  • modules/account_orders.js - Account order queries
  • modules/account_bots.js - Account bot data management

Configuration

  • profiles/ecosystem.config.js - PM2 ecosystem configuration
  • profiles/bots.json - Bot configuration
  • profiles/general.settings.json - Global settings (auto-generated on first run)
  • profiles/ama_profiles.json - AMA configuration profiles

Claw Integration (claw/)

  • index.js - Main export combining all modules
  • modules/claw_bridge.js - JSON bridge for runtime integration
  • modules/zeroclaw_bridge.js - ZeroClaw runtime bridge
  • modules/bitshares_client.js - BitShares connection wrapper
  • modules/chain_queries.js - Chain read helpers
  • modules/chain_broadcast.js - Chain write helpers
  • modules/chain_actions.js - High-level chain operations
  • modules/position_manager.js - Position tracking and management
  • modules/position_health.js - Position health monitoring
  • modules/dexbot_profiles.js - DEXBot2 profile reader
  • modules/dexbot_credential_client.js - Credential daemon client
  • modules/honest_ecosystem.js - HONEST asset helpers
  • modules/short_mpa_strategy.js - Short MPA workflow
  • modules/dynamic_weight_service.js - Dynamic weight policy
  • modules/claw_infra.js - Shared runtime infrastructure
  • docs/AI_BOT_LIBRARY_API.md - API boundary and responsibility split
  • docs/DEXBOT2_TUNING_CHEAT_SHEET.md - Grid tuning reference

Testing

  • tests/ - Comprehensive test suite (unit, integration, scenario tests)

Quick Commands

# Create feature
git checkout test && git pull
git checkout -b feature/my-feature test

# Merge to test
git checkout test && git pull && git merge --no-ff feature/my-feature && git push

# Integrate to dev
git checkout dev && git pull && git merge --no-ff test && git push

# Release to main
git checkout main && git pull && git merge --no-ff dev && git push