hybro: Instructions file for Codex

Development Rules

Conversational Style

• Keep answers short and concise.
• No emojis in commits, issues, PR comments, or code.
• Use direct technical prose without cheerful filler.
• Prefer clear, simple language. Define unavoidable jargon.
• Explain non-trivial work as: problem, concrete example or short trace, then solution. Distinguish required work from optional complexity.
• When the user asks a question, answer it before making edits or running implementation commands.
• When responding to feedback or analysis, explicitly say whether you agree or disagree before describing changes.

Repository Scope

These rules apply to the entire hybro repository. More specific rules in frontend/AGENTS.md and backend/AGENTS.md apply within those directories.

The product flow is:

frontend/ -> backend/ -> A2A agents, Hub relay, and external services

• frontend/: Next.js 16, React 19, and TypeScript UI.
• backend/: Python 3.12 FastAPI platform backend.
• default_agents/: bundled A2A agents and their manifest.
• scripts/: the hybro CLI (POSIX shell), its tests, and the image, migration, and functional-test helpers.
• install.sh: installs the released hybro script.
• Dockerfile: the single product image (UI, API, MCP, embedded MongoDB, and bundled agents behind Caddy on one port).

Do not inspect or treat paths outside this repository as product source unless the task explicitly requires it.

Code Quality

• Read files in full before wide-ranging changes, before editing files not yet fully inspected, and when asked to investigate or audit. Do not base broad changes on search snippets alone.
• Reuse existing services, repositories, adapters, components, hooks, stores, and UI primitives before adding abstractions.
• Keep changes focused on requested behavior. Do not refactor unrelated code opportunistically.
• Prefer the simplest design that satisfies the current requirements. Keep changes minimal and focused; do not add speculative abstractions, fallback paths, or compatibility layers.
• Add defensive handling at untrusted or failure-prone boundaries, such as user input, network calls, persistence, concurrency, and third-party APIs. Do not add redundant guards for states already excluded by validated internal contracts.
• Always ask before removing functionality or code that appears intentional.
• Do not add backward-compatibility layers unless required by an existing public contract or explicitly requested.
• Do not guess third-party APIs. Inspect installed package types, local framework documentation, or official upstream documentation.
• Avoid TypeScript any; use it only when the boundary cannot be typed more precisely and document why.
• Use typed, async-aware Python for I/O paths. Keep HTTP route adapters thin and business behavior in the existing domain/service layers.
• Add or update focused tests for behavior changes. Mock network, LLM, database, wallet, and webhook calls unless explicitly testing integration behavior.
• Treat explicitly marked generated regions as outputs. Update their source and regenerate them instead of editing them directly.
• For review-only requests, do not edit files.