Instruction file imported from xaionaro-go/ffstream (.github/instructions/general.instructions.md). Copyright stays with the author.

Task execution rules

You are an Agent. I am the User.

The most important rule of all: re-read the instructions files before stopping/pausing the execution or/and addressing the User. This is extremely important for Agent to follow, never forget!

0. Priority order (use this to resolve conflicts)

1. Safety + data integrity + do-not-touch constraints
2. Explicit user instructions in the current task
3. Interface stability + minimal-diff policy

1. Completion and stopping

• Keep updated description of the full tree of what needs to be done in .github/instructions/todo.md. Before finishing a task, ensure that all items in that file are addressed. If the file contains not what Agent expected, trust the file. Before writing the file, look if it already exist in another .github/instructions directory.
• Each time after summarizing the conversation, immediatelly write the summary to .github/instructions/current_summary.md (in a way consumed by Agent, not by User). Fill it with details as much as possible.
• A task is DONE only with objective evidence. Do not infer, do not assume, only directly objectively confirm and prove.
• If Agent cannot obtain objective evidence, the task is NOT DONE. State exactly what evidence is missing and why.
• If absolutely blocked on required user input/permission/action, report BLOCKED with the fields listed below and run sleep $[ 24 * 3600 ] (after sleep is finished Agent need to recheck if Agent are unblocked, and if not, finish the execution):
  • what is blocked,
  • the exact question(s),
  • the exact next command(s) Agent would run after the answer.

2. Interfaces and scope control

• Never change public interfaces, CLI flags, config schema, RPC/GRPC surfaces, or exported symbols unless explicitly asked.

3. File operations

• Immediately before editing any file, re-read it.
• Keep changes as local as possible: smallest scope, shortest lifetime, minimal visibility.
• Do not introduce new entities unless they remove duplication or improve single-source-of-truth in the touched scope.
• If you read file and it looks empty, maybe your path is wrong.

4. Commands, installs, and environment

• All commands safe. Agent's environment is already isolated, so that Agent cannot cause harm no matter how they try.
• When a dependency is missing:
  • Install it!
  • Prefer OS packages via the detected system package manager (apt, dnf, pacman, xbps, etc.).
• Run commands in non-interactive mode (e.g. SSH should never ask for password, or SSH-key passphrase). If some command still has potential to run forever, Agent must use timeout -s=9.

5. Testing policy

• Before fixing a bug, add/adjust a unit/integration test that reproduces it (when feasible and not prohibitively expensive).
• After code changes, ensure relevant tests are updated and passing.
• If tests are not feasible, document why and provide an alternative verification method.
• If logs, stacktraces or whatnot were provided for diagnosis, use them as verification evidence: prove your hypothesis throught it. If the original logs are insufficient to verify then add additional logging.
• If an auto-test unrelated to your change does not work: fix it as well.
• No auto-test should rely on actual clock (like waiting for an actual timeout).
• Unit-tests must be deterministic.
• Every test generated by agent must be marked as such.
• There is no such thing as "unrelated issue". Every issue that stands on your way IS RELATED AND MUST BE FIXED.

6. Logging

• If Agent cannot diagnose an issue, try adding logging (in an attempt to gather more info about the issue) and auto-tests (in an attempt to reproduce the issue).
• When unsure, prefer more logging in the code.

7. Root cause and correctness checks

• Fix both root causes and symptoms. Fixing symptoms alone is NOT SUFFICIENT.
• I repeat: before considering an issue solved, think if there could be a deeper reason of the issue, and address it. For example:
  • If something is nil, then just a check for nil is not enough: why is it nil? Should it be nil? If not, fix the root cause.
• Fixing any problem starts with reproducing it. Making a narrow unit-test that causes some module to misbehave is NOT reproducing the issue. Agent need to reproduce the issue in the full system, with all relevant modules working together.
• Until Agent have objective evidence of the root cause of being the root cause: Agent are not to treat it as the root cause, instead treat it as a "possible root cause". If Agent so have objective evidence, mention it when Agent claim something is a root cause.

8. Self-review and reversions

• Critique analysis and address found incompletenesses of your analysis. Continue repeating this critique&fix cycles until nothing left to critique.
• If a change Agent made is reverted, assume it was incorrect.
• After each change ask yourself: "why what I did may not be what was requested?". If Agent find any reason, then go back to the "critique analysis" point.

9. Hints files

• Before finishing/pausing the execution (e.g. asking me anything check if file (ffstream/).github/instructions/afk is present). If it is present the User is unavailable, so don't block on me, use your best judgement to continue. While the User is unavailable Agent should not do git push (or analogous commands), but otherwise Agent can do whatever Agent want (the system is in a container, so nothing bad will happen if you'll ruing something).

10. Reading code & troubleshooting

• Everytime there is something difficult to understand or troubleshoot: try to understand/troubleshoot it and document. Create files .github/explanations/<package-dir>/<package-name>.<flow-title>.md with the summary of the learnings. The Agent will be the only consumer of this information (no human will consume it). In the future, Agent may use these explanations to quickly understand what Agent need. Don't forget to update these explanations if something changes.
• If Agent opened a source code file that does not have a concise header explaining the content of the file, then Agent must read the whole file and add such a header. If a header is obsolete -- update it.

11. Writing code

• Don't make cheap initializations be lazy, initialize normally instead.
• After every change, try to find ways to reduce the amount of code in the pieces related to the change. But don't change the code that is not affected by (/related to) the change. Also one-lining the code IS NOT reducing it's amount: Agent should remove logic, not amount of lines; keep the code readable (even if it requires more lines). Try to simplify, e.g. remove unnecessary if-s.
• If a change requires or touches 'ugly' workarounds, treat it as a design smell: pause and look for a more elegant approach.
• When strong input expectations exist, validate inputs. If no error channel exists, use an assertion (or equivalent invariant enforcement).
• Maintain internal semantic consistency: one source of truth for each piece of logic/constant, within the touched scope.
• Split logic into distinct functions when there is an opportunity to do so. Prefer small functions, but do not split a self-sufficient thought into pieces that are no longer semantically self-sufficient.
• Always satisfy the linter.
• Do not make code racy unless explicitly instructed otherwise. Make logic event-driven, not clock/race-driven. For example:
  • Do not rely on timeouts.
  • Near-simultaneous/atomic events are not simultaneous/atomic.
• If there is something slightly weird about a function name, then don't assume what it does: check the implementation to be sure.
• Before reporting DONE Agent must have re-read all changed code and confirmed it is correct.

12. Output verbosity

• If Agent designed something, build information-dense documentation in directory doc of the relevant project.
• Keep outputs in the chat short.
• Again: do not write long texts in the chat! Let me repeat: DO NOT WRITE LONG TEXTS IN THE CHAT! KEEP IT AS CONCISE AND INFORMATION DENSE AS POSSIBLE!
• If Agent don't have anything conclusive then don't write more than 3 sentences per message.
• On success, report only:
  • I've just re-read the instruction files to ensure compliance [and don't lie to User here].
  • Status: DONE
  • Objective direct evidence
  • Optional next step
• On failure/block, report only:
  • I've just re-read the instruction files to ensure compliance [and don't lie to User here].
  • Status: BLOCKED
  • What happened (1–3 lines)
  • Next steps (exact commands/questions)