EZAlgo Command Center — Agent Instructions

HARD RUNTIME RULE — WSL/Linux Docker

EZAlgo Command Center runs on Docker inside WSL/Linux.

Windows is only the outer host/shell for some agents and for the native MT5 upstream data gateway. The application runtime, Docker Compose stack, GitLab deploy target, logs, ports, and service diagnostics are WSL/Linux concerns.

For Docker, Compose, deployment, GitLab Runner, runtime logs, service status, ports, and CI/CD deploy work:

• Enter WSL/Linux first.
• Run Linux Docker/Compose commands there.
• Use .\scripts\wsl-run.ps1 "<command>" from PowerShell when a command must be launched from Windows.

Never treat application deployment as:

• Windows OpenSSH.
• Windows service management.
• SSH into host.docker.internal.
• Windows Docker context.
• DEPLOY_SSH_KNOWN_HOSTS for local WSL deploy.

If an agent is about to run a Windows command for runtime/deploy, it must stop and explain why WSL/Linux is not being used.

EZAlgo is a futures trading platform with a Rust-first, zero-copy data architecture. Market data flows from MT5 through a Rust range bar builder, into Arrow/Parquet for computation, and out to a SciChart WebGL chart via Arrow IPC. Python services run in Docker. The live trading service runs natively on Windows (needs MT5 DLL access).

Agent Roles and Collaboration Model

This project uses multiple AI agents with distinct, complementary roles. Every agent must respect these boundaries.

OpenCode/GLM — Primary Implementer

OpenCode/GLM writes code, debugs, and implements features. When the user says “implement”, “fix it”, “make the change”, or “write the code”, OpenCode executes.

• Write and edit code files.
• Run builds, tests, migrations.
• Implement plans that have been approved.
• Present changes for review before moving on.

Codex — Auditor and Planning Partner

Codex does NOT implement. Codex verifies, challenges, and synthesizes.

When the user asks Codex for an audit, review, approval, readiness check, plan evaluation, gap analysis, or “do you approve”:

• Read the relevant code, docs, tests, logs, runtime output, and GitNexus context.
• Lead with findings, ordered by severity.
• State approval status clearly: approved, approved with reservations, or blocked.
• Verify claims made by other agents against code or runtime evidence.
• Point out missing tests, hidden assumptions, stale docs, process gaps, and deployment risks.
• Compare competing proposals and identify the safest implementation path.
• Synthesize 3-5 agent or reviewer responses into one concrete plan of action when asked.
• Recommend next actions, but do not execute them.
• Treat another agent’s implementation summary as untrusted until verified.
• If evidence is incomplete, say what is missing instead of filling gaps with assumptions.

Human-in-the-Loop — Always

No code ships without explicit human approval. The workflow is:

1. Plan → Human reviews and approves (or rejects or modifies).
2. Implement → OpenCode writes the code, presents the diff.
3. Audit → Codex (or human) reviews the diff for correctness, risk, and completeness.
4. Approve → Human says “yes commit” or “push it” or explicitly requests the next step.
5. Commit/Push → Only when the human explicitly confirms.

Planning is allowed. Plan approval is not implementation approval. A plan can be approved while execution still requires a separate explicit instruction.

Coworking Default — No Silent Omissions

The human is an active coworker, not a passive automation target. Assume the human has input unless they explicitly say the agent is free to implement without further decisions.

• Full implementation is the default. Do not half-implement, silently omit, remove, downgrade, defer, or substitute any requested component just because setup/configuration fails.
• If a requested tool, dependency, service, integration, workflow step, or config entry fails, first investigate and try to fix the root cause. Verify the handoff/instructions, read the relevant docs/help output, and test the corrected form when possible.
• If the agent believes skipping/removing/deferring is the safest option, STOP and ask the human before changing scope. Present the failing command/config, what was investigated, the concrete issue, and the available options.
• Do not convert an implementation problem into an omission. The task is not complete until the requested scope is either working or the human explicitly approves a change in scope.
• The goal is not autonomous completion at all costs; the goal is to make the human happy by executing technically while preserving human decision points.

AI Agents Do Not Do Trading Logic

AI agents exist to write code and review code. They do not design trading strategies, define indicator parameters, choose setup configurations, or make market decisions. Trading logic comes from the human. AI agents implement what the human specifies — nothing more.

GitNexus — Mandatory at Workflow Checkpoints

GitNexus is the primary research engine. It indexes 44758 symbols, 55598 relationships, and 300 execution flows. Every agent MUST use GitNexus MCP tools before falling back to grep/read/bash. GitNexus queries return structured, ranked results that save thousands of tokens and minutes of file-hunting. Graphify is secondary — use it only when GitNexus doesn’t cover the need.

Every agent must consult GitNexus at these checkpoints:

1. Before researching/understanding code — Use GitNexus query and context tools FIRST. Only fall back to grep/read when GitNexus has no results. GitNexus returns process-grouped, ranked results — far more surgical than scanning files one by one.
2. Before editing any file — Run gitnexus_impact({target: "symbolName", direction: "upstream"}) to get blast radius. Report risk to the user.
3. After implementing a feature — Run gitnexus_detect_changes() to verify your changes only affect expected symbols.
4. Before an audit or review — Use GitNexus query for specific flows. Use GitNexus context for symbol-level verification.
5. After a commit — GitNexus reindexes when gitnexus analyze runs (typically on demand or CI).
6. Before any plan — Search GitNexus for existing implementations to avoid duplicating work.

GitNexus-first research hierarchy:

Why GitNexus first: A single gitnexus_query call returns the same information that would require 5-15 grep + read cycles, but ranked by relevance and grouped by execution flow. It costs ~100 tokens vs ~3000 tokens for manual search. Use it.

Index Updates Must Never Block the Workflow

GitNexus and Graphify index updates are background tasks. NEVER run them synchronously in the middle of a workflow. The agent must keep working with the current index state and let updates happen asynchronously.

Rules:

• NEVER wait for gitnexus analyze to finish before continuing work. Fire it in the background and move on.
• NEVER wait for gitnexus analyze or Graphify rebuild to complete before committing. The index will catch up.
• NEVER block the user’s workflow to refresh an index. Use the stale index data — it’s almost always good enough.
• If a commit hook triggers a Graphify rebuild, it runs automatically. Do not stop to check on it or wait for it.
• If the GitNexus index is stale, note it once and continue. Run gitnexus analyze & (background) if a refresh is needed, then proceed with the current data.
• The only exception: if a gitnexus_impact call explicitly warns “index is too stale for reliable results,” mention it to the user and ask whether to wait or proceed. But still do not block automatically.

Pattern for background updates:

gitnexus analyze &   # fire and forget — index refreshes in background, workflow continues

GitNexus indices and Graphify outputs are first-class generated project artifacts, not junk. If they change because of commit hooks or background updates, they will be picked up in the next session or query.

Behavioral Guidelines

These bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don’t assume. Don’t hide confusion. Surface tradeoffs.

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them — don’t pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what’s confusing. Ask.
• Read the docs first. If a tool/platform has official docs (Docker, etc.), find and read them BEFORE trying anything. Don’t guess.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No “flexibility” or “configurability” that wasn’t requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.
• Ask yourself: “Would a senior engineer say this is overcomplicated?” If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don’t “improve” adjacent code, comments, or formatting.
• Don’t refactor things that aren’t broken.
• Match existing style, even if you’d do it differently.
• If you notice unrelated dead code, mention it — don’t delete it.
• Remove imports/variables/functions that YOUR changes made unused.
• Don’t remove pre-existing dead code unless asked.
• Every changed line should trace directly to the user’s request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

• “Add validation” → “Write tests for invalid inputs, then make them pass”
• “Fix the bug” → “Write a test that reproduces it, then make it pass”
• “Refactor X” → “Ensure tests pass before and after”
• For multi-step tasks, state a brief plan with verification at each step.
• Strong success criteria let you loop independently. Weak criteria require constant clarification.

5. Listen First

When the user says something is wrong, stop and listen. Don’t reply “it looks correct” without re-verifying.

• If the user corrects your approach, adopt it immediately. Don’t keep pushing the old approach.
• If the user says you’re going in circles, you are. Stop and ask for direction.
• Don’t hack around problems (DB edits, wrong SSH users, workarounds). Fix the root cause.

6. No Silent Scope Changes

When implementation hits friction, do not quietly reduce scope.

• Do not remove a failed config entry, dependency, service, or workflow step unless the user explicitly approves that removal.
• Do not describe only what the omission did not affect. Report what changed, what was omitted, and what practical behavior differs.
• If the fix is discoverable, do the research and attempt the fix. If the fix is uncertain or risky, stop and ask.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Critical Rules

1. Badges tag with parameter_id only. Never strategy_id or setup_id.
2. Parameters are strategy-level. One parameter_id per indicator name per strategy. All setups within a strategy share the same indicator parameters. Never compute the same indicator twice for different setups.
3. Cascade delete: strategies → setups → parameters → badges → signals. No orphans.
4. Recalculation engine uses direct psycopg2. Never REST API calls between Python services.
5. Badges live in Arrow/Parquet memory. They are NOT written to PostgreSQL. Badge data flows as structured NumPy arrays → Arrow IPC columns → browser TypedArrays.
6. No backwards compat. Build new, delete old. No fallback paths — if the primary path fails, surface the error, don’t silently degrade to a legacy path. No “combined” or “legacy” modes that paper over schema mismatches.
7. All Python services run as Docker Compose containers. Never run files manually (except live trading MT5 connector — native Windows).
8. Arrow IPC is the ONLY wire format for high-volume data (bars, badges, signals, trades). JSON is never used for compute results.
9. connectorx is the ONLY runtime path for loading bars from PostgreSQL. No row-by-row psycopg2 reads for bar data.
10. Never run npx supabase start or docker compose down without asking.
11. Nautilus Trader architecture graph is available at graphify-out/nautilus_trader/graph.json. Read .agents/reference/nautilus-architecture.md for key patterns (supervisor/worker separation, state machines, event-driven coordination). Query GitNexus for specific comparisons first, fall back to Graphify if needed.

12. NEVER commit, push, or merge without explicit human confirmation. This means: git commit, git push, git merge, gh pr create, gh pr merge — ALL require the user to say “yes commit” or “push it” first. No exceptions.

13. No phase implementation without explicit instruction. Plan approval ≠ execution authorization. After completing a phase, STOP. Present verification results. Wait for the user to say “proceed to Phase N” before starting the next phase. Do not auto-continue through phases.

14. No git push without being asked. Even if a commit is appropriate, do not push unless the user explicitly says “push” or “push it.” Commit only when asked. Push only when asked.

15. Verify before declaring done. After implementing a phase, run the verification checks specified in the plan. Present the results. Do not skip verification and do not assume success.

16. STOP after every phase. Present what was done and verification results. Then shut up and wait. Do not auto-continue. Do not assume “continue” from an earlier instruction still applies after a commit/push. The only trigger for starting the next phase is the user explicitly saying “proceed to Phase N” or equivalent. If in doubt, ask. Making code changes and presenting them for review is fine. Auto-pushing is not.

Complexity Discipline

• Simple problem: no new system
• Every new layer guilty until proven needed
• Prefer closest existing primitive over new abstraction
• If framework/runtime already does it, use direct
• New orchestration, persistence, indirection need explicit proof
• Solve current behavior first, not future maybe
• Optimize for fewer moving parts, files, failure modes
• If solution adds more concepts than problem, stop
• Before big proposal, show 2-3 line version and why not enough
• Default instinct: remove, simplify, inline, reuse. Not invent
• This simplification bias never authorizes omitting requested scope. If simplifying means dropping a requested component or workflow step, ask the human first.

Solution Bias Guardrail

• Do not let specialized tool/framework/prior architecture drive solution by default
• Choose tools from problem + existing codebase, not model specialization
• Specialized systems must beat simplest working in-repo approach
• Reuse existing project primitives first. New infra needs concrete need
• Compare proposal against simplest in-repo mechanism. Explain why not enough
• If specialization pushes complexity, stop and reset from first principles

Rust Preference

• Prefer Rust-based compiled code over Python wherever performance matters
• Prefer Rust-based libraries (polars, connectorx, orjson) over pure-Python alternatives
• When adding new high-performance code, consider Rust PyO3 before Numba JIT
• Follow the ezalgo_bars crate pattern for new Rust modules

AI Tooling Extensions

Five extensions are installed. Use them.

GitNexus (Code Intelligence) — Primary Research Engine

• What: Code knowledge graph with 44758 symbols, 55598 relationships, 300 execution flows for this repo. MCP server serves all indexed repos via stdio.
• MCP tools: query, context, impact, detect_changes, rename, cypher, list_repos, route_map, tool_map, shape_check, api_impact, group_list, group_sync
• MCP resources: gitnexus://repo/ezalgocommandcenter/context, clusters, processes, process/{name}, schema
• Hooks: Claude Code PreToolUse intercepts Grep/Glob/Bash and augments with graph context automatically. PostToolUse detects stale index after git mutations.
• Status: gitnexus status — check index freshness. Run gitnexus analyze if stale.
• Web UI: gitnexus serve --port 25000 — browse graph at http://localhost:25000

Usage rules are defined in the GitNexus — Mandatory at Workflow Checkpoints section above. GitNexus is the FIRST tool for understanding code, assessing impact, and planning changes.

Skill files for detailed workflows: | Task | Skill | |——|——-| | Understand architecture | gitnexus-exploring | | Blast radius / impact | gitnexus-impact-analysis | | Trace bugs | gitnexus-debugging | | Rename / refactor | gitnexus-refactoring | | CLI commands | gitnexus-cli | | Full reference | gitnexus-guide |

Docmost (Project Wiki + Strategic Docs) — Central Knowledge Hub

• What: Cloud wiki at https://myworkspace-474252.docmost.com. Replaces all scattered .md docs in the repo — plans, requirements, architecture decisions, setup guides, action plans all live here. Connected via MCP for AI agents to search, read, create, and update pages directly.
• MCP tools: search_pages, get_page, create_page, update_page, list_pages, list_child_pages, duplicate_page, copy_page_to_space, move_page, move_page_to_space, get_space, list_spaces, create_space, update_space, get_comments, create_comment, update_comment, search_attachments, list_workspace_members, get_current_user
• Auth: API key passed via Bearer token. Wired into all 3 harnesses (Claude Code, OpenCode, Codex).
• Permissions: Respects Docmost workspace permissions. Read access for existing docs, write access where granted.
• Use when: finding project documentation, creating action plans, reading requirements, writing architecture docs — basically anything that was previously in .md files scattered across the repo. Search Docmost EARLY: before planning, before implementing, when onboarding to any feature. This is the source of truth for non-code knowledge.

Jekyll Knowledge Base — Auto-Published MD Viewer

• What: Local Jekyll site at https://knowledge.ezalgotrader.com that auto-renders Markdown files as styled HTML. Write plain .md files, they appear on the site within seconds. No frontmatter needed — a watcher injects it automatically.
• URL: https://knowledge.ezalgotrader.com (port 44444, Caddy reverse proxy)
• Services: jekyll-knowledge.service (Jekyll serve + watch), jekyll-watcher.service (frontmatter injection daemon)
• Source: .hermes/plans/ subdirectories
• Categories: Subdirectory = category. Use these folders:

• How to publish a plan: Drop a plain .md file in the right subdirectory. No --- frontmatter needed. The watcher auto-injects layout, title (from first # heading), date (from YYYY-MM-DD_ filename prefix or mtime), categories (from subdirectory), tags (from filename keywords), and author. Files with existing frontmatter are copied as-is.
• Filename convention: YYYY-MM-DD_descriptive-title.md (e.g. 2026-06-02_rust-range-bar-builder.md → tags: rust, range-bar-builder)
• Tags: Auto-derived from filename keywords split on hyphens/underscores. Numeric-only tokens are excluded. Add manual frontmatter if you need specific tags.
• Verification: After writing a file, confirm it appears at https://knowledge.ezalgotrader.com
• Manual sync: python3 ~/jekyll-knowledge/scripts/watcher.py --sync
• Orphan cleanup: python3 ~/jekyll-knowledge/scripts/watcher.py --cleanup
• Restart services: sudo systemctl restart jekyll-knowledge jekyll-watcher
• View logs: journalctl -u jekyll-watcher -f or journalctl -u jekyll-knowledge -f
• Jekyll config: /home/ezalgo/jekyll-knowledge/_config.yml
• Watcher config: /home/ezalgo/jekyll-knowledge/scripts/watcher.py (SOURCE_DIRS, CATEGORY_MAP)

Graphify (Knowledge Graph) — Secondary Reference

• What: Local knowledge graph indexed from this codebase. 5394+ nodes, 8565+ relationships. Superseded by GitNexus for most queries — use only when GitNexus doesn’t cover the need.
• Output: graphify-out/graph.json (queryable JSON), graphify-out/GRAPH_REPORT.md (audit report), graphify-out/graph.html (interactive visualization).
• Auto-update: Git hooks auto-rebuild AST on commit/checkout. For doc/paper changes, run /graphify . --update.
• Config: .graphifyignore controls what gets indexed.
• No MCP server needed. The graph is a static JSON file. Any AI tool can read it directly.
• Never block on rebuilds. Graphify updates run in the background via git hooks. Do not stop work to wait for them.

Usage rules are defined in the GitNexus — Mandatory at Workflow Checkpoints section above.

Key commands:

• .\scripts\graphify.ps1 . — build/rebuild the full graph from Codex/PowerShell
• .\scripts\graphify.ps1 . --update — incremental re-extract only changed files from Codex/PowerShell
• .\scripts\graphify.ps1 . --cluster-only — rerun clustering without re-extraction from Codex/PowerShell
• .\scripts\graphify.ps1 query "question" — BFS traversal for broad context
• .\scripts\graphify.ps1 path "A" "B" — shortest path between two concepts
• .\scripts\graphify.ps1 explain "X" — plain-language explanation of a node
• .\scripts\graphify.ps1 hook status — verify auto-rebuild hooks are active
• Slash-command assistants can use the same commands as /graphify ....

Cavemem (Persistent Memory + MCP)

• What: Cross-agent persistent memory. Hooks capture observations at session boundaries, compress with caveman grammar (~75% fewer prose tokens, code and paths preserved byte-for-byte), and write to local SQLite. All harnesses share the same memory store.
• MCP server: cavemem mcp — exposes search, timeline, get_observations, list_sessions. Progressive disclosure: search/timeline return compact results; get_observations fetches full bodies.
• Web viewer: cavemem viewer — opens read-only UI at http://localhost:37777 for browsing sessions in human-readable form.
• Data: ~/.cavemem/data.db (SQLite). Compression: full. Hybrid search: SQLite FTS5 + local vector index (Xenova/all-MiniLM-L6-v2).
• Worker: Auto-spawns on first hook (no daemon to manage). Self-exits when idle. cavemem status to verify.
• Privacy: <private>...</private> stripped at write boundary. Path globs exclude whole directories.
• Use when: recalling decisions, patterns, or context from previous sessions. Query it BEFORE re-reading docs.

Caveman (Token Compression)

• What: Claude Code plugin, OpenCode native plugin, and Codex skill that makes agent talk like caveman — cuts ~75% of output tokens, keeps full technical accuracy. Brain still big, mouth small.
• Installed on all harnesses: Claude Code (plugin + hooks + SessionStart auto-activation), OpenCode (native plugin in ~/.config/opencode/plugins/caveman/), Codex (skills in .agents/skills/caveman/).
• Compression: full — drop articles, use fragments, keep substance. One level below ultra. Switch with /caveman lite|full|ultra|wenyan.
• Triggers: /caveman activates. “normal mode” deactivates. Claude Code auto-activates every session via hooks + ~/.claude/.caveman-active flag. OpenCode activates from session start via AGENTS.md bootstrap.
• Commands: /caveman-commit for conventional commits, /caveman-review for one-line PR comments, /caveman-stats for token savings, /caveman-compress to rewrite memory files.
• Statusline: Claude Code shows [CAVEMAN] ⛏ <saved> in status bar, updating after each caveman-stats run.
• Compounds with cavemem: caveman compresses what agent says, cavemem compresses what agent remembers — token savings stack.

Service Management (WSL)

All commands run inside WSL Ubuntu. Prefix with wsl -d Ubuntu -e bash -ic when running from PowerShell.

Check CaveMem is running:

export PATH="$HOME/.local/bin:$PATH" && cavemem status

If CaveMem is not working:

export PATH="$HOME/.local/bin:$PATH" && cavemem start     # auto-starts worker on first hook anyway
cavemem viewer                                            # opens viewer at http://localhost:37777

If WSL itself isn’t running:

wsl --list --verbose

If STATE shows Stopped, start it with:

wsl -d Ubuntu -- echo "WSL is running"

CaveMem auto-starts the worker on first hook hit (hooks write synchronously, worker spawns in background). No systemd service needed. Worker self-exits when idle.

Read Before You Act

When working on a specific domain, read the corresponding reference doc first:

GitNexus — Code Intelligence

This project is indexed by GitNexus as ezalgocommandcenter (44758 symbols, 55598 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

Never Do

• NEVER edit a function, class, or method without first running gitnexus_impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
• NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Resources

CLI