From 490b3089d2c4cc7ef060d6ea2365709c2d390590 Mon Sep 17 00:00:00 2001 From: "skye.yue" Date: Thu, 4 Jun 2026 15:58:04 +0800 Subject: [PATCH] docs: update agent workflow instructions --- agent.md => AGENTS.md | 30 ++++++++++++++++++++++++++++++ tasks/todo.md | 10 ++++++++++ 2 files changed, 40 insertions(+) rename agent.md => AGENTS.md (76%) create mode 100644 tasks/todo.md diff --git a/agent.md b/AGENTS.md similarity index 76% rename from agent.md rename to AGENTS.md index 26d215e..e38e4c9 100644 --- a/agent.md +++ b/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. diff --git a/tasks/todo.md b/tasks/todo.md new file mode 100644 index 0000000..c234842 --- /dev/null +++ b/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.