metis: Instructions file for Codex

Agent Development Guide

This file is for AI coding agents contributing to Metis. Treat it as repository-level operating guidance. User and system instructions always take precedence.

Objective

Help developers change Metis quickly without sacrificing scope control, compatibility, or verification. Prefer evidence from the repository over assumptions.

Start Every Task

1. Restate the requested outcome and concrete acceptance criteria.
2. Read git status --short and strictly preserve unrelated user changes and dirty worktree files.
3. Search for relevant code, tests, docs, and existing abstractions before editing.
4. Read the nearest applicable AGENTS.md if a nested one exists.
5. Identify affected modes and surfaces:
   • CLI / TUI: Interactive terminal UI (src/modes/interactive/, vendor/metis-tui/)
   • Headless / Print: Non-interactive execution (src/modes/print-mode.ts)
   • RPC / JSON: Programmatic streaming and JSON protocols (src/modes/rpc/, src/rpc-entry.ts)
   • Server: HTTP / SSE server engine (src/modes/server/)
   • Desktop: Electron host (desktop/main.cjs) + React frontend (desktop/src/)
   • SDK / Core: Public API and core session management (src/core/agent-session.ts, src/core/sdk.ts)
   • Extensions & Packages: User extensions, MCP, package manager (src/core/extensions/, src/core/package-manager.ts)
6. Decide the smallest validation set that can prove the change works.

If .codegraph/ exists and its tools work, use CodeGraph before broad text search for code understanding (codegraph explore "<query>", codegraph node <symbol-or-file>). If the index is missing or malformed, state that once and fall back to rg and targeted file reads.

Fast Investigation & Search Protocols (Efficiency & Anti-Hang)

1. NEVER run bare git grep --untracked or unconstrained grep -r at repo root: The repository contains massive untracked directories (node_modules, desktop/renderer/assets, eval_results/, temporary benchmarks, .codegraph). Bare untracked searches crawl gigabytes of assets and will hang or spawn background tasks that eat minutes of time.
2. Always use scoped rg (ripgrep) or targeted paths:
   • For Desktop frontend: rg "keyword" desktop/src/
   • For Core / Server: rg "keyword" src/
   • When searching root, always exclude heavy dirs: rg --glob '!node_modules' --glob '!desktop/renderer' --glob '!eval_results' --glob '!dist' "keyword"
3. Correlate git status --short with search: If a feature was recently added or is work-in-progress, its files may be untracked (?? desktop/src/components/harness/). Run git status --short first to spot untracked candidate directories, then inspect them directly (view_file or rg "keyword" <untracked_dir>/).
4. Fast-Path UI & Styling Diagnosis (No Over-Engineering): When user reports UI sizing, alignment, or spacing discrepancies (e.g. "搜索尺寸小了，和右侧同步"):
   • DO NOT write ad-hoc Python PNG decoders, binary decompression scripts, or pixel-sampling loops. That burns 5–10 minutes on trivial CSS properties.
   • Directly inspect the JSX and Tailwind/CSS box model:
     • Height & Box Model: Does one element use h-[28px] with border (border-box outer height = 28px) while the adjacent button uses h-[28px] with shadow-btn (1px spread box-shadow makes outer visual height = 30px)?
     • Typography: Is text text-[12px] while the sibling button is text-[12.5px]?
     • Width & Padding: Is an input w-24 / w-28 (112px) cramped because padding (pl-8 pr-7 = 60px) leaves only 52px for text?
     • Surface & Hover: Does the input use bg-field while the button uses bg-surface?
   • Rapid Verification:
     • Run targeted Vitest: npm test -- test/desktop-react-*.test.ts (executes in <1s).
     • Run Desktop build: npm --prefix desktop run build (Vite builds in ~3s).