AGENTS.md — Approved Sections (Working Draft)

Status: 2 sections approved by Andres, awaiting final commit to AGENTS.md Convention: One file, overwrite in place. No version suffixes. We edit this file directly until final.

This document is the staging area for sections going into AGENTS.md. As Andres approves each section, it lands here. The final committed version of AGENTS.md is the production target.

Section 1: Jekyll Knowledge Base — PUBLISH EVERY PLAN

Every plan, action item, brainstorm, or architectural decision MUST be published to the knowledge base. No exceptions. If you create a plan and it only exists in chat, it doesn’t exist.

Write a plain .md file to the correct .hermes/plans/ subdirectory. The watcher auto-publishes it to https://knowledge.ezalgotrader.com — no frontmatter needed, no manual steps.

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

Tags are critical — they are how we find related content across categories. Tags are auto-derived from filename keywords (hyphens and underscores become tag boundaries). Use descriptive, topic-focused filenames to get good tags.

Tag vocabulary — use these 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 it appears at https://knowledge.ezalgotrader.com

⚠ If you lost context and don’t understand these categories, tags, or the publishing workflow — STOP. Do not guess. Do not skip publishing. Read the full reference at .hermes/plans/documentation/2026-06-02_knowledge-base-setup.md before proceeding.

Section 2: Working with Andres — The Baseline Workflow

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

The ONLY exception: when Andres explicitly says “just do it” / “skip the plan” / “go ahead” — confirm the scope in one sentence, then execute. No further confirmation loops. But this is opt-in, not default. When in doubt, plan.

The Four Non-Negotiables

1. Search for an available skill FIRST.

This is non-negotiable. When Andres asks for research, implementation, or any other work, the very first action is to check installed skills. The compound-engineering (CE) skills are the baseline toolkit — use them whenever they apply. When work is specific to a language or framework, search for that domain’s skill. Skills dramatically improve output quality and reduce time-to-solution.

The friction this rule prevents: agent tries, agent gets it wrong, Andres says “will you search the docs,” agent says “oh yeah, here it is.” That is wasted hours. The answer is already in the installed skills. Use them.

2. Use the MCP servers.

Multiple MCP servers are configured for this project. Examples include context7 (for up-to-date library/framework documentation lookup) and sequential-thinking (for structured multi-step reasoning). Treat MCP servers as first-class tools — check what’s available, use what’s relevant. They are not optional.

3. Look up online documentation BEFORE implementing.

Especially for code-related work — bug fixes, implementation, framework usage, API calls. Official docs are the source of truth. We do not guess at API surfaces, we do not pattern-match from training data, we do not skip the docs because “it probably works the way I remember.”

4. Publish critical online documentation INTO the project.

When we look up online documentation and find material that future work will need, capture it as a project doc and make it accessible to all AI agents. The MD knowledge base (Section 1) and Docmost are the destinations. Reference materials do not survive across chat sessions, but project docs persist across sessions and harness switches. This is why we scrape and publish docs to the knowledge base — to make the answer always available.

CE Skills (Baseline Toolkit, 35 Installed)

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 the skill file before using a skill. The skill files contain the workflow.

The Pet Peeve Rule

It is unacceptable to do the same wrong thing twice. It is unacceptable to push back three or more times on the same problem without searching for the answer. If the agent is going in circles, the answer is always in one of these places, in this order of preference:

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

The agent must check these in order before asking Andres to repeat themselves. The friction this prevents: Andres says “search the docs” after an hour of failures. The docs had the answer in 15 seconds. The agent should have looked.

Open Items Before Final Commit to AGENTS.md

• Codex audit — do these two sections conflict with any existing AGENTS.md rules?
• Final wording review with Andres (cut down where possible)
• Confirm placement in AGENTS.md (currently planned: after the Docmost section, since both are knowledge publishing tools)
• Update the “Read Before You Act” table to include the knowledge base row
• Add skill-usage rule to “Behavioral Guidelines” or “Critical Rules”

Approved Sections

1. ✅ Jekyll Knowledge Base (2026-06-02)
2. ✅ Working with Andres — Baseline Workflow (2026-06-02)

Full Operational Reference

For operational detail on the knowledge base (services, manual sync commands, watcher config, frontmatter override), see: .hermes/plans/documentation/2026-06-02_knowledge-base-setup.md (published at https://knowledge.ezalgotrader.com/2026/06/02/knowledge-base-setup/)