AGENTS.md — Timmy Time Development Standards for AI Agents

Read CLAUDE.md for architecture patterns and conventions.

Communication Protocol

Before making changes, always:

Read CLAUDE.md and AGENTS.md fully
Explore the relevant src/ modules to understand existing patterns
Explain what you're changing and why in plain English
Provide decision rationale - don't just make changes, explain the reasoning

For Timmy's growth goals:

Improve reasoning in complex/uncertain situations: think step-by-step, consider alternatives
When uncertain, state uncertainty explicitly rather than guessing
Document major decisions in DECISIONS.md

Non-Negotiable Rules

Tests must stay green. Run make test before committing.
No cloud dependencies. All AI computation runs on localhost.
No new top-level files without purpose. Don't litter the root directory.
Follow existing patterns — singletons, graceful degradation, pydantic-settings.
Security defaults: Never hard-code secrets.
XSS prevention: Never use innerHTML with untrusted content.

Agent Roster

Build Tier

Local (Ollama) — Primary workhorse. Free. Unrestricted. Best for: everything, iterative dev, Docker swarm workers.

Kimi (Moonshot) — Paid. Large-context feature drops, new subsystems, persona agents. Avoid: touching CI/pyproject.toml, adding cloud calls, removing tests.

DeepSeek — Near-free. Second-opinion generation, large refactors (R1 for hard problems). Avoid: bypassing review tier for security modules.

Review Tier

Claude (Anthropic) — Architecture, tests, docs, CI/CD, PR review. Avoid: large one-shot feature dumps.

Gemini (Google) — Docs, frontend polish, boilerplate, diff summaries. Avoid: security modules, Python business logic without Claude review.

Manus AI — Security audits, coverage gaps, L402 validation. Avoid: large refactors, new features, prompt changes.

Docker Agents

Container agents poll the coordinator's HTTP API (not in-memory SwarmComms):

GET  /internal/tasks    → list tasks open for bidding
POST /internal/bids     → submit a bid

COORDINATOR_URL=http://dashboard:8000 is set by docker-compose.

make docker-build       # build image
make docker-up          # start dashboard
make docker-agent       # add a worker

File Conventions

Pattern	Convention
New route	`src/dashboard/routes/<name>.py` + register in `app.py`
New template	`src/dashboard/templates/<name>.html` extends `base.html`
New subsystem	Add to existing `src/<package>/` — see module map in CLAUDE.md
New test	`tests/<module>/test_<feature>.py` (mirror source structure)
Secrets	Via `config.settings` + startup warning if default
DB files	Project root or `data/` — never in `src/`

Roadmap

v2.0 Exodus (in progress): Voice + Marketplace + Integrations v3.0 Revelation (planned): Lightning treasury + .app bundle + federation

3.0 KiB Raw Permalink Blame History