EZAlgo Command Center — Agent Instructions

Eleven Commandments — Read First

Full detail below. Read one section? Read this one.

1. Where things run — Windows hosts MT5/Supabase/LiveTrading. Hyper-V Ubuntu hosts everything else. → HARD RUNTIME RULE
2. GitNexus mandatory — Always start with GitNexus, never with grep/read/bash. ~100 tokens vs ~3000. → GitNexus — Mandatory
3. Plan → discuss → approve → plan → move forward — Never talk-then-implement, even with build mode on. → Working with Andres
4. Search for available skill FIRST — CE skills = baseline toolkit. → Four Non-Negotiables
5. Use MCP servers — context7, sequential-thinking, etc. First-class tools. → Four Non-Negotiables
6. Look up online docs BEFORE implementing — Don’t guess at APIs. → Four Non-Negotiables
7. Publish critical online docs INTO project — Capture in knowledge base or Docmost. → Four Non-Negotiables
8. Pet Peeve Rule — Never do same wrong thing twice. Never loop three times without using tools. → Pet Peeve Rule
9. PUBLISH EVERY PLAN to knowledge base — If only exists in chat, it doesn’t exist. → Jekyll Knowledge Base
10. NEVER commit/push/merge without explicit human confirmation — “yes commit” or “push it” required. → Critical Rules
11. Cascade delete: strategies → setups → parameters → badges → signals — No orphans. Ever. → Critical Rules

Section index:

• HARD RUNTIME RULE — Where Things Run
• GitNexus — Mandatory at Workflow Checkpoints
• Behavioral Guidelines
• Critical Rules
• Complexity Discipline
• Solution Bias Guardrail
• Rust Preference
• AI Tooling Extensions
• Jekyll Knowledge Base — PUBLISH EVERY PLAN
• Working with Andres — The Baseline Workflow
• Read Before You Act
• GitNexus — Code Intelligence

HARD RUNTIME RULE — Where Things Run

Runtime split across two hosts. Fact, not suggestion. Agents who get this wrong waste hours.

Implications:

• Docker, Compose, deploy, GitLab Runner, runtime logs, ports, CI/CD: work in Hyper-V Ubuntu directly.
• MT5 connector, Windows-native Supabase, anything needing MT5 DLL: work in Windows (PowerShell).
• If agent about to run Windows command for runtime/deploy, stop + explain why Hyper-V Ubuntu not used.

Never treat app deploy as:

• Windows OpenSSH for app deploy (MT5/Supabase side only)
• Windows service management for app services
• SSH into host.docker.internal for app services
• Windows Docker context for app services
• DEPLOY_SSH_KNOWN_HOSTS for local Hyper-V Ubuntu deploy

EZAlgo = futures trading platform, Rust-first, zero-copy data architecture. Market data: MT5 (Windows) → Rust range bar builder (Hyper-V Ubuntu) → Arrow/Parquet for compute → SciChart WebGL chart via Arrow IPC. Python services run in Docker on Hyper-V Ubuntu. Live trading service runs natively on Windows (needs MT5 DLL access).

GitNexus — Mandatory at Workflow Checkpoints

GitNexus = primary research engine. Mandatory — every agent MUST use before falling back to raw file search. Indexes 44758 symbols, 55598 relationships, 300 execution flows. Queries return structured, ranked results = save thousands of tokens + minutes of file-hunting. Graphify secondary — use only when GitNexus doesn’t cover.

Always start with GitNexus. Never start with grep/read/bash. Better research, more targeted, for less money — GitNexus cheaper than raw file search by wide margin (~100 vs ~3000 tokens for equivalent coverage). Raw file search = fallback, not default.

Every agent consults GitNexus at these checkpoints:

1. Before researching/understanding code — GitNexus query + context tools FIRST. Fall back to grep/read only when GitNexus has no results.
2. Before editing any file — gitnexus_impact({target: "symbolName", direction: "upstream"}) = blast radius. Report risk to user.
3. After implementing feature — gitnexus_detect_changes() verify changes only affect expected symbols.
4. Before audit/review — GitNexus query for specific flows. GitNexus context for symbol-level verification.
5. After commit — GitNexus reindexes when gitnexus analyze runs (on demand or CI).
6. Before any plan — Search GitNexus for existing implementations to avoid duplication.

GitNexus-first research hierarchy:

Why GitNexus first: single gitnexus_query = same info as 5-15 grep + read cycles, ranked by relevance + grouped by execution flow. ~100 tokens vs ~3000 for manual search. Use it.

Index Updates Must Never Block Workflow

GitNexus + Graphify index updates = background tasks. NEVER run synchronously mid-workflow. Keep working with current index state, let updates happen async.

Rules:

• NEVER wait for gitnexus analyze before continuing. Fire background, move on.
• NEVER wait for gitnexus analyze or Graphify rebuild before committing. Index catches up.
• NEVER block user workflow to refresh index. Use stale data — almost always good enough.
• Commit hook triggering Graphify rebuild = runs automatically. Don’t stop, don’t wait.
• GitNexus index stale = note once, continue. gitnexus analyze & (background) if refresh needed, proceed with current data.
• Only exception: gitnexus_impact warns “index too stale for reliable results” — mention to user, ask wait or proceed. Still don’t block automatically.

Pattern for background updates:

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

GitNexus indices + Graphify outputs = first-class generated project artifacts, not junk. If they change because of commit hooks or background updates, picked up next session or query.

Behavioral Guidelines

Bias toward caution over speed. Trivial tasks: use judgment.

1. Think Before Coding

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

• State assumptions explicitly. Uncertain? Ask.
• Multiple interpretations? Present them — don’t pick silently.
• Simpler approach exists? Say so. Push back when warranted.
• Unclear? Stop. Name what’s confusing. Ask.
• Read docs first. Tool/platform has official docs (Docker, etc.)? Find + read BEFORE trying. Don’t guess.

2. Simplicity First

Min code that solves problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No “flexibility”/”configurability” that wasn’t requested.
• No error handling for impossible scenarios.
• 200 lines could be 50? Rewrite.
• “Would senior engineer say overcomplicated?” Yes? Simplify.

3. Surgical Changes

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

• Don’t “improve” adjacent code, comments, formatting.
• Don’t refactor things that aren’t broken.
• Match existing style, even if you’d do differently.
• Unrelated dead code? Mention — don’t delete.
• Remove imports/variables/functions YOUR changes made unused.
• Don’t remove pre-existing dead code unless asked.
• Every changed line traces directly to 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 bug” → “Write test that reproduces it, then make it pass”
• “Refactor X” → “Ensure tests pass before and after”
• Multi-step tasks: state brief plan with verification at each step.
• Strong success criteria = loop independently. Weak = constant clarification.

5. Listen First

User says something wrong? Stop + listen. Don’t reply “looks correct” without re-verifying.

• User corrects approach? Adopt immediately. Don’t keep pushing old approach.
• User says going in circles? You are. Stop + ask for direction.
• Don’t hack around problems (DB edits, wrong SSH users, workarounds). Fix root cause.

6. No Silent Scope Changes

Implementation hits friction? Don’t quietly reduce scope.

• Don’t remove failed config entry/dependency/service/workflow step unless user explicitly approves removal.
• Don’t describe only what omission didn’t affect. Report what changed, what omitted, what behavior differs.
• Fix discoverable? Do research, attempt fix. Fix uncertain/risky? Stop + ask.

Guidelines working if: fewer unnecessary diff changes, fewer rewrites due to overcomplication, clarifying questions before implementation rather than after mistakes.

Critical Rules

1. Badges tag with parameter_id only. Never strategy_id or setup_id.
2. Parameters = strategy-level. One parameter_id per indicator name per strategy. All setups within strategy share same indicator parameters. Never compute 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. 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 — primary path fails? Surface error, don’t silently degrade to legacy. No “combined”/”legacy” modes papering over schema mismatches.
7. All Python services run as Docker Compose containers on Hyper-V Ubuntu. Never run files manually (except live trading MT5 connector — native Windows).
8. Arrow IPC = ONLY wire format for high-volume data (bars, badges, signals, trades). JSON never used for compute results.
9. connectorx = 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 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.

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

13. No phase implementation without explicit instruction. Plan approval ≠ execution authorization. Phase complete? STOP. Present verification results. Wait for user to say “proceed to Phase N” before starting next phase. Don’t auto-continue.
14. No git push without being asked. Commit appropriate? Don’t push unless user explicitly says “push”/”push it.” Commit only when asked. Push only when asked.
15. Verify before declaring done. Implement phase? Run verification checks specified in plan. Present results. Don’t skip verification, don’t assume success.
16. STOP after every phase. Present what was done + verification results. Shut up + wait. Don’t auto-continue. Don’t assume “continue” from earlier instruction still applies after commit/push. Only trigger for next phase = user explicitly saying “proceed to Phase N” or equivalent. Doubt? Ask. Code changes for review = fine. Auto-pushing = not.

Complexity Discipline

• Simple problem: no new system
• Every new layer guilty until proven needed
• Prefer closest existing primitive over new abstraction
• 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
• Solution adds more concepts than problem? Stop
• Big proposal? Show 2-3 line version + why not enough
• Default instinct: remove, simplify, inline, reuse. Not invent
• Simplification bias never authorizes omitting requested scope. Dropping requested component = ask human first.

Solution Bias Guardrail

• Don’t 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 = concrete need
• Compare proposal against simplest in-repo mechanism. Explain why not enough
• Specialization pushes complexity? Stop + 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
• Adding new high-performance code? Consider Rust PyO3 before Numba JIT
• Follow ezalgo_bars crate pattern for new Rust modules

AI Tooling Extensions

GitNexus (Code Intelligence) — Primary Research Engine

• What: Code knowledge graph, 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 + augments with graph context. PostToolUse detects stale index after git mutations.
• Status: gitnexus status — check index freshness. gitnexus analyze if stale.
• Web UI: gitnexus serve --port 25000 — browse graph at http://localhost:25000

Usage rules in GitNexus — Mandatory at Workflow Checkpoints above. GitNexus = FIRST tool for understanding code, assessing impact, 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 repo — plans, requirements, architecture decisions, setup guides, action plans all live here. MCP for AI agents to search/read/create/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 via Bearer token. Wired into all 3 harnesses (Claude Code, OpenCode, Codex).
• Permissions: Docmost workspace permissions. Read access for existing docs, write where granted.
• Use when: finding project docs, creating action plans, reading requirements, writing architecture docs — basically anything previously in .md files scattered across repo. Search Docmost EARLY: before planning, before implementing, when onboarding. Source of truth for non-code knowledge.

Graphify (Knowledge Graph) — Secondary Reference

• What: Local knowledge graph indexed from codebase. 5394+ nodes, 8565+ relationships. Superseded by GitNexus for most queries — use only when GitNexus doesn’t cover.
• Output: graphify-out/graph.json (queryable JSON), graphify-out/GRAPH_REPORT.md (audit), graphify-out/graph.html (visualization).
• Auto-update: Git hooks auto-rebuild AST on commit/checkout. Doc/paper changes: /graphify . --update.
• Config: .graphifyignore controls indexing.
• No MCP server needed. Static JSON file. Any AI tool can read directly.
• Never block on rebuilds. Graphify updates = background via git hooks. Don’t stop work to wait.

Usage rules in GitNexus — Mandatory above.

Key commands:

• .\scripts\graphify.ps1 . — build/rebuild full graph from Codex/PowerShell
• .\scripts\graphify.ps1 . --update — incremental re-extract changed files
• .\scripts\graphify.ps1 . --cluster-only — rerun clustering without re-extraction
• .\scripts\graphify.ps1 query "question" — BFS for broad context
• .\scripts\graphify.ps1 path "A" "B" — shortest path between concepts
• .\scripts\graphify.ps1 explain "X" — plain-language node explanation
• .\scripts\graphify.ps1 hook status — verify auto-rebuild hooks active
• Slash-command assistants: 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/paths preserved byte-for-byte), write to local SQLite. All harnesses share memory store.
• MCP server: cavemem mcp — search, timeline, get_observations, list_sessions. Progressive disclosure: search/timeline = compact, get_observations = full bodies.
• Web viewer: cavemem viewer — read-only UI at http://localhost:37777 for browsing sessions.
• 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). Self-exits when idle. cavemem status to verify.
• Privacy: <private>...</private> stripped at write boundary. Path globs exclude directories.
• Use when: recalling decisions, patterns, context from previous sessions. Query BEFORE re-reading docs.

Caveman (Token Compression)

• What: Claude Code plugin, OpenCode native plugin, Codex skill — agent talks like caveman, ~75% output token cut, full technical accuracy. Brain 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, fragments OK, keep substance. One level below ultra. Switch: /caveman lite|full|ultra|wenyan.
• Triggers: /caveman activates. “normal mode” deactivates. Claude Code auto-activates every session via hooks + ~/.claude/.caveman-active. OpenCode activates from session start via AGENTS.md bootstrap.
• Commands: /caveman-commit conventional commits, /caveman-review one-line PR comments, /caveman-stats token savings, /caveman-compress rewrite memory files.
• Statusline: Claude Code shows [CAVEMAN] ⛏ <saved> in status bar, updating after caveman-stats.
• Compounds with cavemem: caveman compresses what agent says, cavemem compresses what agent remembers — savings stack.

Service Management (Hyper-V Ubuntu)

All commands inside Hyper-V Ubuntu. SSH in or use terminal multiplexer of choice from there.

Check CaveMem running:

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

CaveMem 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

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

Jekyll Knowledge Base — PUBLISH EVERY PLAN

Every plan, action item, brainstorm, or architectural decision MUST be published to knowledge base. No exceptions. Plan only in chat? Doesn’t exist.

Write plain .md to correct .hermes/plans/ subdirectory. Watcher auto-publishes to https://knowledge.ezalgotrader.com — no frontmatter, no manual steps.

Filename: YYYY-MM-DD_descriptive-title.md (e.g. 2026-06-02_rust-range-bar-builder.md)

Tags critical — how we find related content across categories. Auto-derived from filename keywords (hyphens + underscores = tag boundaries). Use descriptive, topic-focused filenames for good tags.

Tag vocabulary — use when applicable:

• Core platform: trading, signals, backtesting, strategy, data-pipeline, indicators
• Frontend: chart, frontend, badge
• Backend: backend, rust, infra, observability
• Concerns: architecture, refactor, security, performance, testing

After writing: Verify appears at https://knowledge.ezalgotrader.com

⚠ Lost context? Don’t understand categories, tags, or publishing workflow? STOP. Don’t guess. Don’t skip publishing. Read full reference at .hermes/plans/documentation/2026-06-02_knowledge-base-setup.md before proceeding.

Working with Andres — The Baseline Workflow

Default interaction pattern = plan → discuss → approve → plan → move forward. Never talk-then-implement. Not even for test. Not even when build mode on. Build mode = permission system, not workflow override — baseline holds regardless.

ONLY exception: Andres explicitly says “just do it”/”skip the plan”/”go ahead” — confirm scope in one sentence, then execute. No further confirmation loops. Opt-in, not default. Doubt? Plan.

Four Non-Negotiables

1. Search for available skill FIRST.

Non-negotiable. Andres asks for research, implementation, or any other work? First action = check installed skills. CE (compound-engineering) skills = baseline toolkit — use when applicable. Work specific to language/framework? Search for that domain’s skill. Skills dramatically improve output, reduce time-to-solution.

Friction this prevents: agent tries, gets wrong, Andres says “search docs,” agent says “oh yeah, here it is.” Wasted hours. Answer already in installed skills. Use them.

2. Use MCP servers.

Multiple MCP servers configured. Examples: context7 (up-to-date library/framework docs), sequential-thinking (structured multi-step reasoning). MCP servers = first-class tools — check available, use relevant. Not optional.

3. Look up online docs BEFORE implementing.

Especially code-related — bug fixes, implementation, framework usage, API calls. Official docs = source of truth. Don’t guess at APIs, don’t pattern-match from training, don’t skip because “probably works how I remember.”

4. Publish critical online docs INTO project.

Look up online docs, find material future work will need? Capture as project doc, make accessible to all AI agents. MD knowledge base (Jekyll section above) + Docmost = destinations. Reference materials don’t survive across chat sessions; project docs persist across sessions + harness switches. This why we scrape + publish docs to knowledge base — make answer always available.

CE Skills (Baseline Toolkit)

Plan first: ce-plan, ce-brainstorm, ce-ideate, ce-strategy Build: ce-work, ce-work-beta, ce-worktree Debug: ce-debug Test: ce-test-browser, ce-test-xcode Review: ce-code-review, ce-doc-review, ce-agent-native-audit Commit/PR: ce-commit, ce-commit-push-pr, ce-resolve-pr-feedback Memory: ce-compound, ce-compound-refresh, ce-sessions Domain: ce-frontend-design, ce-dhh-rails-style, ce-agent-native-architecture Research: ce-web-researcher, ce-slack-research, ce-best-practices-researcher Cleanup: ce-simplify-code, ce-clean-gone-branches Other: ce-setup, ce-product-pulse, ce-release-notes, ce-proof, ce-demo-reel, ce-gemini-imagegen, ce-polish-beta, ce-optimize, ce-report-bug, ce-riffrec-feedback-analysis

Always load skill file before using skill. Skill files = workflow.

Pet Peeve Rule

Unacceptable: do same wrong thing twice. Unacceptable: push back 3+ times on same problem without searching for answer. Agent going in circles? Answer always in one of these places, in this order:

1. Installed skills (~/.config/opencode/skills/, .agents/skills/, .claude/skills/)
2. MD knowledge base (/home/ezalgo/workspace/ezalgoCommandCenter/.hermes/plans/)
3. Docmost wiki (https://myworkspace-474252.docmost.com/s/ezalgocommandcenter)
4. Project reference docs (.agents/reference/, AGENTS.md, CLAUDE.md)
5. MCP server tools (context7, sequential-thinking, etc.)
6. Online official docs

Agent checks these in order before asking Andres to repeat themselves. Friction this prevents: Andres says “search docs” after hour of failures. Docs had answer in 15 sec. Agent should have looked.

Read Before You Act

Working on specific domain? Read corresponding reference doc first:

GitNexus — Code Intelligence

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

Any GitNexus tool warns index stale? npx gitnexus analyze in terminal first.

Always Do

• MUST run impact analysis before editing any symbol. Modify function/class/method? gitnexus_impact({target: "symbolName", direction: "upstream"}) = blast radius (direct callers, affected processes, risk level). Report to user.
• MUST run gitnexus_detect_changes() before committing — verify changes only affect expected symbols + execution flows.
• MUST warn user if impact analysis returns HIGH/CRITICAL risk before proceeding.
• Exploring unfamiliar code? gitnexus_query({query: "concept"}) for execution flows, not grepping. Returns process-grouped results ranked by relevance.
• Need full context on specific symbol — callers, callees, which execution flows it participates in? gitnexus_context({name: "symbolName"}).

Never Do

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

Resources

CLI