Timmy-time-dashboard/AGENTS.md

AGENTS.md — Timmy Time Development Standards for AI Agents

Read CLAUDE.md for architecture patterns and conventions.

---

Communication Protocol

Before making changes, always:

1. Read CLAUDE.md and AGENTS.md fully
2. Explore the relevant src/ modules to understand existing patterns
3. Explain what you're changing and why in plain English
4. 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

1. Tests must stay green. Run python3 -m pytest tests/ -x -q before committing.
2. No direct pushes to main. Branch protection is enforced on Gitea. All changes reach main through a Pull Request — no exceptions. Push your feature branch, open a PR, verify tests pass, then merge. Direct git push origin main will be rejected by the server.
3. No cloud dependencies. All AI computation runs on localhost.
4. No new top-level files without purpose. Don't litter the root directory.
5. Follow existing patterns — singletons, graceful degradation, pydantic-settings.
6. Security defaults: Never hard-code secrets.
7. XSS prevention: Never use innerHTML with untrusted content.

---

Merge Policy (PR-Only)

Gitea branch protection is active on main. This is not a suggestion.

The Rule

Every commit to main must arrive via a merged Pull Request. No agent, no human, no orchestrator pushes directly to main.

The Workflow

1. Create a feature branch:  git checkout -b fix/my-thing
2. Make changes, commit locally
3. Run tests:                python3 -m pytest tests/ -x -q
4. Push the branch:          git push --no-verify origin fix/my-thing
5. Create PR via Gitea API or UI
6. Verify tests pass (orchestrator checks this)
7. Merge PR via API or UI

Why This Exists

On 2026-03-14, Kimi Agent pushed bbbbdcd directly to main — a commit titled "fix: remove unused variable in repl test" that removed result = from 7 test functions while leaving assert result.exit_code on the next line. Every test broke with NameError. No PR, no test run, no review. The breakage propagated to all active worktrees.

Orchestrator Responsibilities

The Hermes loop orchestrator must:

• Run pytest -x -q in each worktree BEFORE committing
• Never push to main directly — always push a feature branch + PR
• Verify test results before merging any PR
• If tests fail, fix or reject — never merge red

---

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