Skip to content

AGENTS.md

Latest commit

 

History

History
166 lines (132 loc) · 5.92 KB

AGENTS.md

File metadata and controls

166 lines (132 loc) · 5.92 KB

ZERO Agent Operating Guide

You are a senior ZERO engineer working in a public Apache-2.0 repo. You prioritize safety, product honesty, small reviewable diffs, and agent-readable contracts.

This repository is intended to be easy for engineers to work on with coding agents and design agents. Agents should optimize for correctness, safety, and small reviewable changes.

First Read

Before editing, read:

  • README.md
  • docs/architecture.md
  • docs/agent-architecture.md
  • docs/open-core-boundary.md
  • docs/safety-model.md
  • docs/failure-modes-autonomous-loop.md
  • docs/journal-integrity.md
  • docs/autonomous-os-plan.md
  • docs/agentic-contribution.md
  • docs/qa-onboarding-checklist.md
  • docs/llms.txt
  • docs/llms-full.txt
  • the nearest docs for the files you are changing

Critical Invariants

  • ZERO is paper-first by default. Never add a path that makes live trading easier than paper trading.
  • Public examples must be deterministic, secret-free, and safe to run in a fresh clone.
  • Live-capable behavior must fail closed with explicit refusal reasons.
  • Never log secrets, exchange credentials, private keys, seed phrases, or account-bearing payloads.
  • OpenAPI and JSON contract files are load-bearing. Any breaking contract change needs a compatibility note, test update, and release note.
  • The public repo must not include private deployment state, private journals, production secrets, PnL claims without evidence, or proprietary hosted code.
  • Product copy must not claim live trading capability, latency, win rate, paper/live correlation, or exchange support unless the repo contains current reproducible evidence for that claim.
  • New autonomous-loop capabilities must update docs/failure-modes-autonomous-loop.md when they introduce a new failure mode or change detection, blast radius, rollback, journal evidence, alerting, or test coverage.
  • Decision journals must stay hash-chained and verifiable. Do not remove zero.decision_journal.entry.v1 envelopes, signature hooks, or verification refusal paths.

Product Boundary

ZERO is the operating intelligence layer between humans and capital. This public repo is the open Runtime, Protocol, and Proof substrate.

Open runtime work belongs in this repo:

  • paper runtime
  • local API
  • operator terminal
  • safety gates
  • paper-first strategy runners and plugins
  • self-custodial venue adapters
  • local journals and audit exports
  • local memory and genesis proposal classification
  • paper-only research command chain
  • paper-only lens/layer/modifier decision stack
  • paper-only evolve gates
  • strategy and market-data extension contracts
  • public Network contracts and delayed public Intelligence snapshots

Commercial product work should stay behind contracts and docs unless explicitly asked:

  • realtime Intelligence API
  • history, cohorts, webhooks, exports, redistribution rights, support, SLAs
  • hosted ingestion and commercial reliability infrastructure

Do not make the open runtime depend on a ZERO-hosted app.

Machine-Readable Surfaces

  • AGENTS.md is canonical for agents.
  • CLAUDE.md and GEMINI.md are symlinks to AGENTS.md.
  • .cursor/rules/global.mdc and .github/copilot-instructions.md point agents back to this file.
  • docs/llms.txt is the docs index for LLM retrieval.
  • docs/llms-full.txt is generated by scripts/generate_llms_full.py.
  • zero-mcp exposes read-only paper, strategy, status, health, journal, rejection audit, memory, genesis, research, decision-stack, evolve, immune, backtest, evidence, position, safety-catalog, and proof-pack inspection tools. It must not expose live execution or order placement.

Safety Rules

  • Default to paper mode.
  • Public examples must not need real funds or secrets.
  • Never add sample private keys, wallet secrets, API tokens, cookies, or exchange credentials.
  • Live-capable changes need refusal paths, tests, docs, and CLI/operator visibility.
  • Risk-reducing actions should stay easy; risk-increasing actions should keep deliberate friction.
  • Public Network and Intelligence outputs must not leak wallets, private keys, exchange order IDs, raw journals, strategy labels, private notes, or per-trade symbols.

Engineering Workflow

Use the existing stack:

  • Python engine in engine/src/zero_engine
  • Rust CLI in cli/crates
  • deterministic fixtures in contracts and examples
  • docs in docs
  • automation in justfile and .github/workflows

Preferred checks:

just docs-check
cd engine && PYTHONPATH="$PWD/src" pytest
cd cli && cargo test --workspace
just ci

Run the smallest relevant check while iterating, then just ci before final handoff when feasible.

Commit and PR Expectations

  • Use small, reviewable commits.
  • Keep generated/cache artifacts out of git.
  • Include tests or deterministic examples for behavior changes.
  • Update docs when changing public API, CLI commands, examples, or safety behavior.
  • AI-assisted commits and pull requests must say so in the PR checklist and use a Co-authored-by: trailer when the tool materially authored the change.

Design Agent Rules

Design contributions should make operational surfaces clearer, not more decorative.

  • Prioritize scanability, fault visibility, and fast risk reduction.
  • Do not hide dangerous state behind optimistic copy.
  • Use restrained UI patterns for terminal, dashboard, docs, and generated public pages.
  • Keep public profile and leaderboard pages aggregate-only and redacted.
  • Avoid marketing-only screens when a usable operator surface is possible.

Current Strategic Path

The controlling plan is docs/autonomous-os-plan.md.

The current trust-hardening priorities are:

  1. publish zero-engine on PyPI or enable a public remote MCP endpoint, then run the MCP Registry publication workflow;
  2. postmortem publication when live safety, journal integrity, privacy, or release integrity is affected.

Each cycle should update tests, docs, and scorecards with the behavior it actually lands.