đź‘›

Agent Guide

Agent Guide (Pinke)

This document defines how autonomous coding agents should work in this repo. It is optimized for “thinking” agents: explicit phases, clear stop conditions, and verifiable outcomes.

Role

You are an autonomous coding agent. Complete exactly one task per run.

Default behavior: implement the smallest change that satisfies the task’s acceptance criteria.

Non-Negotiable Principles

  1. Follow the codebase
  2. Match existing patterns, naming, architecture, and styling.
  3. Keep scope locked
  4. Don’t refactor or “improve nearby things” unless required for correctness.
  5. Make review easy
  6. Small, incremental commits/changes; minimal file touches.
  7. Never assume success
  8. Verify via manual checks and tests (if present).
  9. Be explicit
  10. If you had to guess, document assumptions.
  11. No secrets
  12. Never log, print, or commit credentials/tokens. Use .env patterns already present.

Repo Navigation Hints

Start here: - UI templates: /templates/ - Static assets: /app/templates/static/ (CSS/JS/images) - Backend logic: root Python files and /app/... (as applicable) - Docs: /docs/

When a task references “balancing” or “visualize”, search for: - visualize, balance, numbers, inflow, outflow, net, rule, htmx

Required Workflow (Thinking Model)

Phase 0 — Pick a Task

Choose a task based on: - Complexity level - Risk/impact - What you can confidently validate end-to-end

Output (in notes/PR): - Task chosen - Why now - Expected files touched

Phase 1 — Recon & Source of Truth

Before writing code: - Find the route/entrypoint - Identify where the logic lives (backend vs frontend vs shared helper) - Locate current calculations/state derivations - Scan for existing helpers that should be reused

Output: “Recon Notes” - Entry points (routes/templates/components) - Relevant files/functions - Data flow (what computes what) - Gotchas (caching, filtering, HTMX partials, rendering)

Phase 2 — Plan (Write it down before coding)

Write a short plan:

  1. Goal (user-visible outcome)
  2. Constraints (what must not change)
  3. Approach (steps)
  4. Risks (where it can fail)
  5. Verification (exact steps/commands)

Ambiguity rule:
Ask one clarifying question only if you are blocked. Otherwise choose the safest interpretation and record it under Assumptions.

Phase 3 — Implement (Small Steps)

Rules: - Prefer existing patterns and utilities. - Avoid new abstractions unless reused ≥2 times. - Keep changes localized. - Update docs/comments only when behavior changes.

If the task is UI-related: - Ensure both light and dark theme still look reasonable. - Avoid hardcoding colors in many places—centralize to CSS variables if the project already does that.

Phase 4 — Verify (Definition of Done Contract)

Before marking done, verify:

  1. App runs (no startup errors)
  2. Acceptance criteria met exactly
  3. No regressions (quick smoke test of adjacent flows)
  4. Tests: run uv run pytest if tests exist in that area
  5. Docs updated if behavior/user flow changed

Output: “Verification Notes” - Commands run + results - Manual steps tested (URLs, buttons clicked, filters applied) - Edge cases checked (if relevant) - Any known limitations

Phase 5 — Completion Note (Required)

Add a âś… Done: section below the task (in the tasks list / ticket / PR body).

Use this exact template:

  • âś… Done:
  • Summary: (1–3 sentences)
  • Files changed: (bullets)
  • Behavior changes: (what user will notice)
  • How to test: (steps + command)
  • Assumptions: (only if needed)
  • Verification Notes: (commands + key checks)

Stop Conditions (When to Ask / When to Stop)

Ask a clarifying question only if: - You can’t locate the relevant code after recon - Requirements conflict - Multiple interpretations lead to different user-visible outcomes and you can’t pick safely

If blocked but can still provide value: - Ship a partial with clear “Blockers” and “Next steps”.

“Do Not Do” List

  • No unrelated refactors
  • No dependency swaps unless required
  • No formatting-only changes
  • No speculative features
  • No broad renaming
  • No changing API contracts without task explicitly requiring it

UI Task Checklist (Use for CSS/Visual tasks)

  • [ ] Looks correct in light mode
  • [ ] Looks acceptable in dark mode
  • [ ] No console errors
  • [ ] At least one narrow viewport checked (responsive sanity check)
  • [ ] Colors match palette/guide if defined