Imported from nirholas/crypto-vision (packages/ucai/AGENTS.md). Install upstream with npx skills add nirholas/crypto-vision --skill ucai. Copyright stays with the author.

UCAI Development Guidelines

Universal Contract AI Interface (UCAI) 🔗 ABI to MCP | The open standard for connecting AI agents to blockchain. MCP server generator for smart contracts. Claude + Uniswap, Aave, ERC20, NFTs, DeFi. Python CLI, Web3 integration, transaction simulation. Polygon, Arbitrum, Base, Ethereum EVM chains. Claude, GPT, LLM tooling, Solidity, OpenAI.

Project Overview

UCAI is built with Python. See the README for full documentation.

Project Philosophy

• We have unlimited Claude credits — never cut corners, never settle for "good enough." Build the best possible version of everything.
• Always be improving — every session should leave the codebase better than it was found. Proactively fix tech debt, improve performance, harden security, expand test coverage, and refine UX.
• Ship production-quality code — write thorough tests, handle edge cases, add meaningful error messages, and document public APIs.
• Think big, execute precisely — propose ambitious improvements but implement them carefully and incrementally.

No Mocks, No Fakes, No Stubs

• Always write full, real implementations — never use placeholder data, mock responses, fake APIs, TODO stubs, or hardcoded dummy values.
• Connect to real services — if a feature calls an API, implement the actual HTTP client with proper error handling, retries, and timeouts.
• No "coming soon" or empty shells — every function must do real work. If a dependency isn't available yet, build the adapter so it's ready to plug in.
• No # TODO: implement later — if you write a function signature, implement it fully right now. We have the credits. Do the work.
• Tests use real logic — test against actual behavior, not mocked internals. Use integration tests with real data flows where possible.

Code Quality Standards

• Python strict typing — use type hints everywhere, no Any types, run mypy/pyright checks.
• Error handling everywhere — every async call needs try/except, every API response needs validation, every edge case needs a code path.
• Consistent patterns — follow existing code conventions. If the codebase uses a pattern, replicate it. Don't introduce competing paradigms.
• Self-documenting code — prefer clear naming over comments. When comments are needed, explain why, not what.
• DRY but not over-abstracted — extract shared logic into helpers, but don't create abstractions for single-use cases.

Continuous Improvement Mindset

Every time you touch a file, ask yourself:

1. Can I make this faster? — optimize hot paths, reduce allocations, cache aggressively
2. Can I make this safer? — add validation, tighten types, handle edge cases, sanitize inputs
3. Can I make this cleaner? — reduce duplication, improve naming, simplify logic, extract helpers
4. Can I make this more testable? — add missing tests, improve coverage, add integration tests
5. Can I make this more observable? — add structured logging, metrics, health checks, error context

If you see something broken or improvable while working on something else, fix it. Leave every file better than you found it (Boy Scout Rule).

Proactive Engineering

• Don't wait to be asked — if you notice dead code, remove it. If you see a missing index, add it. If docs are stale, update them.
• Anticipate failures — add retry logic, circuit breakers, graceful degradation, and timeout handling where appropriate.
• Think about the next developer — write clear commit messages, helpful code comments, and self-documenting APIs.
• Performance matters — profile before optimizing, but always be aware of O(n) vs O(1), unnecessary re-renders, and N+1 queries.
• Security is non-negotiable — never log secrets, always validate inputs, use parameterized queries, and follow least privilege.

Build & Run Discipline

• Always verify your changes compile — run the appropriate build/lint command after changes.
• Always run tests — run pytest (or the appropriate test command) after changes to ensure nothing is broken.
• If a build or test fails, fix it immediately — never leave the codebase in a broken state.

Completion & Follow-Through

• Finish what you start — don't leave partial implementations. If you open a file to change one thing and notice three others, fix all four.
• Verify end-to-end — after implementing a feature, trace the full path. Confirm it works.
• Run the full test suite — don't just test the file you changed. Run all tests to catch regressions.
• Check for orphans — after refactoring, ensure no dead imports, unused exports, or dangling references remain.
• Update docs and types — if you change an API, update the spec, README, type definitions, and any consuming code.

Git Identity

• Always commit and push as nirholas — before any git commit or push, configure:

  git config user.name "nirholas"
  git config user.email "nirholas@users.noreply.github.com"
  

Terminal Management

• ⚠️ ALWAYS use background terminals (isBackground: true) for EVERY command — no exceptions. This ensures a terminal ID is returned so you can retrieve output and kill the terminal.
• ⚠️ ALWAYS kill EVERY terminal after use — call kill_terminal on every terminal ID as soon as you have the output, whether the command succeeds or fails. Zero terminals should remain open when you finish a task. This is non-negotiable.
• Kill terminals immediately — as soon as you have the output you need, kill the terminal. Do not leave any terminals lingering. Leaked terminals accumulate and degrade Codespaces performance.
• Never use foreground terminals (isBackground: false) — foreground shells block, cannot be killed, and cause stale session issues in Codespaces. Always use isBackground: true.
• In GitHub Codespaces, agent-spawned terminals may be hidden — they still work. Do not assume a terminal is broken if you cannot see it.
• If a terminal appears unresponsive, kill it and create a new one rather than retrying in the same terminal.
• Chain commands with && to minimize the number of terminal invocations.
• Use timeouts on commands that might hang — never let a terminal block indefinitely.
• Workflow: run_in_terminal (isBackground: true) → get_terminal_output → kill_terminal. Every single time. No exceptions.

Contributing

• Follow the existing code style
• Test changes before submitting PRs
• Update documentation when adding features
• See CONTRIBUTING.md for full guidelines