Aeloon: Instructions file for Claude Code

Aeloon — Agent Development Guide

This file is loaded automatically by Claude Code. Read it before making any changes.

---

Code Style

Tooling

Tool	Command	Purpose
ruff	ruff check --fix .	Lint + auto-fix
ruff	ruff format .	Format
pytest	pytest	Run tests

Always run both before committing. CI enforces ruff==0.15.6 — use the same version locally.

Key Rules

• Line length: 100 (formatter enforced, E501 silenced)
• Imports: sorted by ruff (isort-compatible)
• Naming: snake_case functions/vars, PascalCase classes, UPPER_SNAKE module-level constants only
• Type hints: required on all public functions and class methods
• Async: prefer async/await for all I/O; keep sync wrappers thin
• Never rename camelCase args that mirror external API contracts — add # noqa: N803 instead

Commit Format (Conventional Commits)

<type>(<scope>): <short summary>

Types: feat, fix, chore, docs, test, refactor, perf, ci

feat(channels): add Discord channel support
fix(cron): prevent duplicate job on restart
chore: bump ruff to 0.15.7

---

Project Layout

aeloon/
├── agent/          # Core agent loop, context builder, memory, subagents
│   └── tools/      # Tool implementations (filesystem, web, exec, cron, mcp)
├── channels/       # One file per platform (slack.py, telegram.py, ...)
├── cli/            # Typer CLI commands — thin wrappers only
├── config/         # Pydantic schema + loader + path helpers
├── providers/      # LLM provider abstractions + registry
├── skills/         # Built-in skill directories (each has SKILL.md)
└── templates/      # Runtime templates (SOUL.md, AGENTS.md, USER.md, ...)
bridge/             # WhatsApp bridge (Node.js / TypeScript — separate process)
tests/              # pytest test suite
docs/               # Team documentation

---

Extension Patterns

Add a Channel

# aeloon/channels/myplatform.py
from aeloon.channels.base import BaseChannel

class MyPlatformChannel(BaseChannel):
    name = "myplatform"
    display_name = "My Platform"

    async def start(self) -> None:
        # connect and listen; call self._handle_message() on each event
        ...

    async def stop(self) -> None:
        ...

    async def send(self, msg) -> None:
        ...