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.

Merge Strategy: Squash-Only, Linear History

Gitea enforces:

• Squash merge only. No merge commits, no rebase merge. Every commit on main is a single squashed commit from a PR. Clean, linear, auditable.
• Branch must be up-to-date. If a PR is behind main, it cannot merge. Rebase onto main, re-run tests, force-push the branch, then merge.
• Auto-delete branches after merge. No stale branches.

The Workflow

1. Create a feature branch:  git checkout -b fix/my-thing
2. Make changes, commit locally
3. Run tests:                tox -e unit
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:         {"Do": "squash"}

If behind main before merge:

1. git fetch origin main
2. git rebase origin/main
3. tox -e unit
4. git push --force-with-lease --no-verify origin fix/my-thing
5. Then merge the PR

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 tox -e unit in each worktree BEFORE committing
• Never push to main directly — always push a feature branch + PR
• Always use {"Do": "squash"} when merging PRs via API
• If a PR is behind main, rebase and re-test before merging
• Verify test results before merging any PR
• If tests fail, fix or reject — never merge red

---

QA Philosophy — File Issues, Don't Stay Quiet

Every agent is a quality engineer. When you see something wrong, broken, slow, or missing — file a Gitea issue. Don't fix it silently. Don't ignore it. Don't wait for someone to notice.

Escalate bugs:

• Test failures → file with traceback, tag [bug]
• Flaky tests → file with reproduction details
• Runtime errors → file with steps to reproduce
• Broken behavior on main → file IMMEDIATELY

Propose improvements — don't be shy:

• Slow function? File [optimization]
• Missing capability? File [feature]
• Dead code / tech debt? File [refactor]
• Idea to make Timmy smarter? File [timmy-capability]
• Gap between SOUL.md and reality? File [soul-gap]

Bad ideas get closed. Good ideas get built. File them all.

When the issue queue runs low, that's a signal to look harder, not relax.

Dogfooding — Timmy Is Our Product, Use Him

Timmy is not just the thing we're building. He's our teammate and our test subject. Every feature we give him should be used by the agents building him.

• When Timmy gets a new tool, start using it immediately.
• When Timmy gets a new capability, integrate it into the workflow.
• When Timmy fails at something, file a [timmy-capability] issue.
• His failures are our roadmap.

The goal: Timmy should be so woven into the development process that removing him would hurt. Triage, review, architecture discussion, self-testing, reflection — use every tool he has.

---

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