docs: align agent workflow guidelines

[piotr-iohk]

Twin: synonymdev/bitkit-android#1360

This PR standardizes agent verification, independent review, and model reporting across Bitkit Android and iOS.

Description

• Defines completion checks using the existing build, unit-test, integration-test, formatting, and translation tooling, and requires agents to fix introduced failures and report commands, results, and blocked checks.

• Recommends independent subagent review with fresh context, using requirements and source revisions without inheriting the implementation conversation.

• Adds informational model names and reasoning effort for Planning/scoping, Implementation, and one aggregated Review entry with an optional round count, allowing the same model throughout and checking session metadata before reporting unknown values.

• Adds a model and reasoning-effort footer to AI review summaries, including Copilot instructions, so each review records its own metadata once rather than repeating it on inline comments.

• Adds optional Twin, Companion, and Dependency links with verified repository-qualified PR numbers, and supports requested relationship or model updates while preserving other description content and dry-run behavior.

• Adds reproducible device-test setup instructions with relevant versions, backend/network, prerequisites and PR-specific deviations so reviewers can run the requested cases.

• Keeps work-in-progress PRs in draft and tells AI reviewers to wait until ready, while documenting that the manually dispatched Claude workflow has no draft guard.

• Strongly recommends author verification before requesting review, with concise Evidence and Gaps notes showing actual results and reasons for unverified cases; existing mandatory checks remain required.

• Gives manual cases (1., 2., sub-cases 2a/2b) and journeys (J1, J2) stable IDs once the PR is open, including drafts. New cases get fresh IDs; removed IDs are retired and never reused. Reviews and results cite IDs plus tested revisions.

Design

N/A — no UI changes.

Preview

N/A — no user-visible changes.

QA Notes

Setup

N/A — documentation-only changes; no device testing required.

Journeys

N/A — no user-visible behaviour change.

Manual Tests

N/A

Automated Checks

• ran git diff --check origin/master...HEAD — passed for the documentation changes.
• ran local documentation checks — changed-file scope, referenced paths, compatibility links, Markdown fences, and shared model/review guidance consistency passed across both repositories.

Evidence

The author agent ran the documentation checks above on 208732fc59db65e8d6fa53ef3c65e26f422f0bbc in the local macOS checkout. They passed on both repositories. No app build or backend was required. Six earlier independent review rounds covered both repositories; their latest full reassessment includes the author-verification recommendation and found no actionable issues.

Stable-ID follow-up at 7d2e702efa06ba0e2796af757c79bb359f8fbee3: documentation scope, git diff --check, Markdown fences, compatibility paths and reference targets passed. The policy matches across Android/iOS. An independent review of this delta found no actionable issues. No application build or device test applies to this documentation-only change.

Gaps

Runtime testing: N/A — documentation-only changes; application builds, unit tests and device tests were not run. The manually dispatched Claude review workflow still has no workflow-level draft guard; this PR documents that limitation without changing automation.

Models used

• Planning/scoping: gpt-6-astra (reasoning: medium), Unknown (reasoning: Not exposed)
• Implementation: gpt-6-astra (reasoning: medium), Unknown (reasoning: Not exposed)
• Review: gpt-6-astra (reasoning: medium), Unknown (reasoning: Not exposed)
• Review rounds: 7

[piotr-iohk]

FYI @JeanlChristophe

[ovitrif]

@piotr-iohk a suggestion for these agent instructions: when an agent writes a PR description, it gives every test an id that stays fixed once the PR is open. Manual tests are numbered (1., 2., a sub-case as 2a) and journeys are J1, J2, and so on. A new test takes the next free id, and a removed test leaves its id unused. Reviews and test reports name tests by these ids, so a renumbered list makes earlier results point at the wrong test.

[piotr-iohk]

@ovitrif Agreed — addressed in 7d2e702. Manual cases use explicit 1., 2. labels (sub-cases 2a/2b), and journeys use J1, J2. IDs stay fixed from PR opening, including drafts: additions take fresh IDs after the highest assigned ID; removed cases leave retired IDs with a reason, never reused or left as runnable tasks. Reviews, Evidence/Gaps and test reports cite the case ID and tested revision, so an unchanged ID does not make old evidence current.

Updated AGENTS.md, the shared PR command and its examples, the PR template, and Copilot review guidance on both platforms. Documentation scope, whitespace, Markdown fences, compatibility paths and reference checks passed; the shared policy is identical. Independent review of both diffs found no actionable issues. Runtime testing is N/A for this documentation-only change. Both PRs remain drafts.