docs: add task-based agent workflow and handoff templates

docs/agent-workflow/LOG.md

@@ -0,0 +1,34 @@
+# Execution log: [task name]
+
+## Current state
+
+Keep this section short and update it before handoff.
+
+- State: not started / investigating / implementing / ready for review / stopped / complete
+- Current revision and working-tree changes:
+- Accepted findings and retained changes:
+- Unresolved questions, blockers and unrun checks:
+- Next action:
+- Do not repeat these attempts unless their assumptions change:
+- Evidence location and access limits:
+
+## Attempts
+
+Copy this block for each meaningful attempt; record failures as well as successes.
+
+### A01 — [hypothesis or investigation question]
+
+- Expected mechanism / observable result:
+- Change or probe; base and candidate identity:
+- Commands, environment and raw evidence:
+- Observations and correctness results:
+- Interpretation and uncertainty:
+- Decision: retain / revert / inconclusive; why:
+- Follow-up or correction to an earlier conclusion:
+
+## Handoff / stop
+
+- Reason for stopping and budget used:
+- What is complete, what remains:
+- Review status and next decision needed:
+- Applicable validation stages completed/pending (local, PR, post-merge, remote settings):

docs/agent-workflow/README.md

@@ -0,0 +1,81 @@
+# Task-based agent workflow
+
+Use this workflow for multi-step investigations, complex fixes, or work that must
+survive a session handoff. Small, self-contained edits do not need these files.
+[AGENTS.md](../../AGENTS.md) remains the source of project-wide rules; these
+records describe one task and do not grant additional permissions.
+
+## Three records
+
+Copy the templates into a task-specific working directory:
+
+| Record | Purpose |
+| --- | --- |
+| [TASK.md](TASK.md) | The agreed objective, scope, constraints, acceptance checks, budget and stopping conditions. |
+| [LOG.md](LOG.md) | Current state, attempts, evidence, decisions and the next action. |
+| [REVIEW.md](REVIEW.md) | An independent assessment tied to the exact changes inspected. |
+
+Use a unique task directory under the scratch location configured for your
+environment. Keep machine-specific paths in personal configuration. Do not
+commit routine scratch artifacts. When preparing a PR, include the useful findings
+and reproducible checks; provide accessible evidence links or attachments for
+reviewers rather than relying only on local paths. Never retain credentials.
+
+## Agree, execute, review
+
+1. **Agree on the task.** Populate TASK from the user's request. Resolve choices
+   that change the outcome, architecture, compatibility, dependencies or external
+   state before dependent work. Do not ask again about already authorized work.
+   TASK is the single source for the current acceptance rules. Record any agreed
+   change there with its reason and update affected verification scripts together.
+   Update the current scope and acceptance text when approval changes the task
+   phase; an appended approval must not contradict an obsolete read-only boundary.
+   An agent must not relax a gate just because an attempt failed it.
+2. **Work within the boundary.** Read TASK and the current-state section of LOG.
+   Inspect the live checkout before acting. For each meaningful attempt, state a
+   hypothesis, make a scoped change, run the appropriate checks and record the
+   outcome. Reuse existing tests and benchmark runners. Separate observations
+   from causal explanations and open questions.
+3. **Keep the handoff current.** Update LOG after a meaningful result or before
+   ending a session. Put the current version, accepted findings, unresolved work
+   and next action at the top. Keep failed attempts and corrections below; mark
+   superseded conclusions instead of silently deleting them. Include evidence
+   paths and exact commands, not a transcript of every tool call.
+4. **Review independently.** Use a separate review session when authorized; do
+   not automatically launch agents. The reviewer reads TASK, the actual diff,
+   relevant code/tests and evidence, rather than relying on the author's summary.
+   Reproduce candidate defects when practical. Record review findings separately
+   from implementation; an author self-check is not an independent review.
+5. **Hand back the decision.** Use REVIEW to distinguish accepted findings,
+   incomplete checks and a completed review with no blocking findings. Fixes go
+   back through verification and review. A review does not authorize a commit,
+   push, merge, deployment or other action outside the user's existing approval.
+
+## Evidence and completion
+
+- Identify the reviewed base and head commits. For uncommitted work, retain a
+  snapshot of the complete diff and any relevant untracked files, with hashes.
+  A HEAD hash alone does not identify a dirty working tree. Later edits require
+  review of the delta and an updated record; old results do not cover new code.
+- For a fix, record whether the regression check fails before and passes after.
+  If this cannot be established, explain the limitation. Do not rewrite the test
+  to match the implementation merely to obtain a pass.
+- For performance work, fix workload, quality requirements, timing scope and
+  baseline before measuring. Retain raw successes and failures. A runner's
+  successful exit is not evidence of a speedup; apply the task's quality and
+  measurement criteria. See the [existing comparison workflow](../../benchmarks/hotpaths/README.md#alternating-comparisons-and-retained-evidence).
+- A review's verdict is **PASS**, **CHANGES_REQUIRED**, or **INCOMPLETE**. PASS
+  means the specified review and required checks completed with no blocking
+  findings; it is not a proof of defect absence. Missing evidence or an unfinished
+  review is INCOMPLETE, not PASS. Optional checks may be omitted with reasons.
+- Distinguish local verification, PR checks, post-merge behavior and remote
+  configuration when the task involves CI or deployment. Record the commit, run
+  links and observed results for each applicable stage. A queued or missing run
+  is pending, not a successful skip; a workflow definition does not configure
+  branch protection. State which stages remain unverified.
+- Stop when the agreed work is complete, the budget is reached, or further work
+  needs missing information or authorization. Record the reason and remaining
+  work. An investigation may end with no change; a budget stop is not task success.
+
+The templates are records for people and agents, not an automated merge gate.
+No GitHub bot, model choice, or additional framework is required.

docs/agent-workflow/REVIEW.md

@@ -0,0 +1,29 @@
+# Review: [task name]
+
+## Identity and coverage
+
+- Reviewer / session (identify an author self-check explicitly):
+- TASK version:
+- Reviewed base and head, or complete working-tree snapshot and hashes:
+- Scope inspected:
+- Validation stage covered (local, PR, post-merge, remote settings, as applicable):
+- Required checks run and evidence:
+- Checks not run and why; distinguish required from optional:
+
+## Findings
+
+For each finding: affected path/location, reachable trigger, observed or expected
+impact, supporting evidence, and whether it was reproduced or remains a hypothesis.
+State explicitly when no blocking findings were found within the inspected scope.
+
+## Verdict
+
+Select exactly one: PASS / CHANGES_REQUIRED / INCOMPLETE.
+
+- Reason:
+- Required follow-up:
+- Limitations:
+
+Tie this verdict to the version above. Later changes need review of their delta;
+retain earlier findings and explain how each was resolved. An incomplete execution
+or missing required check cannot be reported as a pass.

docs/agent-workflow/TASK.md

@@ -0,0 +1,35 @@
+# Task: [short name]
+
+## Objective
+
+- User request / issue:
+- Observable outcome:
+- Starting revision and working-tree state:
+
+## Scope and constraints
+
+- In scope:
+- Out of scope:
+- Invariants (quality, public API, formats, ownership, dependencies as relevant):
+- Current phase and existing authorization:
+- Actions requiring a further decision:
+
+## Acceptance
+
+- Required checks and what each establishes:
+- Regression reproduction or reference behavior:
+- Evidence to retain:
+- For performance tasks: fixed workload, baseline, metrics, quality requirements,
+  environment controls and acceptance thresholds. Omit for other tasks.
+
+## Budget and stopping conditions
+
+- Agreed time / experiment / resource budget:
+- Stop and hand back when:
+- Completion requires:
+
+## Agreed changes to this task
+
+Record date, change, reason and the user decision when required. Also update the
+current scope and acceptance sections; mark superseded rules as historical. Keep
+acceptance scripts consistent with these rules. Leave empty if the task has not changed.

docs/development.md

@@ -2,6 +2,8 @@
 
 Start with [Contributing to RaBitQ](../.github/CONTRIBUTING.md) for setup and your first PR.
 This reference covers tool configuration and changes to library internals.
+For multi-step agent work, use the optional [task workflow and templates](agent-workflow/README.md)
+for goals, execution records, handoffs, and independent review.
 Run commands from the repository root in your activated
 [project environment](../.github/CONTRIBUTING.md#python-environment), after installing
 the [source-build prerequisites](../.github/CONTRIBUTING.md#setup-for-code-changes).