docs: update agent workflow instructions

AGENTS.md

@@ -97,3 +97,33 @@
 - Prefer small, surgical changes that preserve the current architecture.
 - For non-trivial work, update or add planning notes in the existing project style (`docs/plans/`, `task_plan.md`, `progress.md`, or `findings.md`) only when useful for handoff or explicitly requested.
 - Keep the final response grounded in verification evidence: say exactly which commands were run, or say when a validation step was skipped because it requires RTSP, Docker, network, or another external dependency.
+
+## Workflow Orchestration
+
+- Default to a plan-first workflow for any non-trivial task, especially work with 3+ steps or architecture decisions.
+- Write the implementation plan to `tasks/todo.md` as a checklist before editing, and include verification steps rather than implementation steps alone.
+- Start non-trivial work from a detailed spec so execution ambiguity is reduced before code or document changes begin.
+- If execution diverges from the expected path, stop and re-plan instead of pushing ahead on stale assumptions.
+- Prefer subagents for research, exploration, and parallel analysis whenever that helps keep the main context clean.
+- Keep each subagent focused on a single line of investigation.
+- Do not mark work complete without verification; run the relevant tests, inspect the pertinent logs, and compare before/after behavior when the change affects runtime behavior.
+- For non-trivial changes, pause and assess whether there is a simpler or more elegant design before settling on a fix; avoid both hacky patches and unnecessary over-engineering.
+- Treat bug reports and CI failures as end-to-end fix tasks: investigate logs, error output, and failing tests directly, and close the loop without asking the user for avoidable operational detail.
+
+## Task Management
+
+- Use `tasks/todo.md` as the default task tracker: write the plan first, verify the plan before implementation, and keep progress updated as checklist items complete.
+- Record a high-level explanation of meaningful changes as the work proceeds.
+- Add and maintain a review/results section in `tasks/todo.md` so verification outcomes and follow-up findings are captured in the same place as the plan.
+
+## Lessons
+
+- At the start of each session, review any task-relevant entries in `tasks/lessons.md` before beginning implementation work.
+- After each user correction, update `tasks/lessons.md` with the mistake pattern and at least one concrete, executable prevention rule.
+- Continue refining those lessons until the failure pattern stops recurring.
+
+## Core Principles
+
+- Simplicity first: prefer the smallest change that fully solves the problem.
+- No laziness: trace issues to root cause and avoid temporary fixes that would fail a senior-engineer review.
+- Minimal impact: only change the code, docs, and configuration that are necessary for the task.

tasks/todo.md

@@ -0,0 +1,10 @@
+# Task Todo
+
+- [x] Review the current `AGENTS.md` structure and check for existing `tasks/` tracking files.
+- [x] Check in on the plan before implementation and keep this change scoped to the requested documentation update.
+- [x] Merge the requested workflow orchestration, task management, and execution principles into `AGENTS.md`.
+- [x] Verify the updated `AGENTS.md` content against the requested rules and record the review result here.
+
+## Review
+
+- Verified by re-reading `AGENTS.md` and checking the inserted sections for plan-first workflow, `tasks/todo.md` tracking, `tasks/lessons.md` review/update rules, subagent guidance, verification requirements, and simplicity/minimal-impact principles.