docs: add AGENTS.md for AI agent onboarding

[spomichter]

Adds an AGENTS.md to the repo root — a guide for AI coding agents (Openclaw, Codex, Claude Code, Cursor, etc.) working on DimOS.

Covers:

• Quick start (install, run, daemon, status, stop)
• Repo structure with pointers to docs/
• Architecture basics (modules, blueprints, GlobalConfig, transports, daemon)
• Testing (fast/slow, CI command, mypy)
• Pre-commit gotchas
• Code style rules
• Git workflow (branching, PR conventions)
• Common pitfalls (all_blueprints.py, forkserver, type system, macOS)
• Viewer backends (dimos-viewer, rerun-web, foxglove)
• Replay mode

226 lines. Designed to give an agent everything it needs to be productive without reading the entire codebase.

Contributor License Agreement

• I have read and approved the CLA

[greptile-apps]

Greptile Summary

This PR adds AGENTS.md — a 384-line onboarding guide aimed at AI coding agents (Claude Code, Codex, Cursor, etc.) working on DimOS. It covers quick-start commands, repo structure, architecture concepts (modules, blueprints, GlobalConfig, transports), the @skill decorator rules, testing, pre-commit setup, git workflow, and common pitfalls.

The guide is thorough and well-organized, but two issues were found:

• Unclosed code block (line 245): The Minimal correct skill Python code fence is never closed, causing the entire ### System Prompts section (heading, table, surrounding prose, and the ### RPC Wiring heading) to render as raw source code in any Markdown viewer — exactly the content AI agents most need to read correctly.
• Non-idiomatic In/Out import (line 144): The module example teaches from dimos.core.module import Module, In, Out, but In and Out are canonically defined in dimos.core.stream. Every real module in the codebase uses from dimos.core.stream import In, Out. The import works at runtime (since module.py re-imports them internally), but it points agents toward the wrong mental model of the repo structure.

Confidence Score: 3/5

• Safe to merge after fixing the unclosed code fence — the rendering bug actively hides key documentation from agents.
• The content is accurate and valuable, but the unclosed code block is a structural Markdown bug that breaks rendering of a full section in the document. The In/Out import path, while technically functional, teaches non-idiomatic usage counter to the rest of the codebase.
• AGENTS.md — specifically lines 245–278 (unclosed code fence) and line 144 (import path).

Important Files Changed

Filename	Overview
AGENTS.md	New AI-agent onboarding guide — comprehensive and well-structured, but contains an unclosed Python code fence (line 245) that breaks the rendered Markdown for the entire System Prompts section, and teaches a non-idiomatic In/Out import path (dimos.core.module instead of the canonical dimos.core.stream).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[AI Agent reads AGENTS.md] --> B{Quick Start}
    B --> C[uv sync]
    C --> D[dimos run blueprint]
    D --> E{Has McpServer?}
    E -->|Yes - unitree-go2-agentic-mcp| F[dimos mcp list-tools / call]
    E -->|No - all other blueprints| G[dimos agent-send]

    A --> H{Write new module}
    H --> I["from dimos.core.module import Module\nfrom dimos.core.stream import In, Out\nfrom dimos.core.core import rpc"]
    I --> J[Define In/Out streams]
    J --> K["@rpc start() / stop()"]

    A --> L{Write new skill}
    L --> M["@skill + docstring + typed params"]
    M --> N[Return str]
    N --> O[pytest test_all_blueprints_generation.py]
    O --> P[all_blueprints.py regenerated]
    P --> Q[PR to dev branch]

Loading

_{Last reviewed commit: 81fc45c}

[greptile-apps]

Incorrect rpc import path

The import from dimos.core import rpc will fail at runtime. dimos/core/__init__.py is empty, so rpc is not exported from the dimos.core package. Every file in the codebase (70+ occurrences) uses from dimos.core.core import rpc instead.

An AI agent following this guide will produce broken code on its first attempt to write a module.

Suggested change

	from dimos.msgs.sensor_msgs import Image
	from dimos.core.core import rpc

[spomichter]

@greptile