docs(agents): disclose setup and pull request guidance #818

Merged
futondestroyer merged 1 commit from Marcuss2/Longshot:docs/agents-progressive-disclosure into main 2026-11-15 17:50:05 +00:00
Contributor

Type: docs · Risk: low · Tested on: Linux, game-free checks · Needs: none

Why

Agents load AGENTS.md on every task, but much of it applied only to one-time sign-in or the final pull request and
testing stages. Keeping those details in the root file spent attention on irrelevant instructions and made the
always-relevant rules harder to find. The open issue tracker was searched; no issue covers this documentation problem.

What changed

The root agent guide now keeps the general rules and task-keyed pointers, while setup, collaboration and pull request
details live in their canonical guides. AGENTS.md drops from 1,890 to 511 words without dropping the agent-specific
rules; detailed requirements remain in CONTRIBUTING.md and the existing Forgejo guide and skills.

  • AGENTS.md: adds explicit triggers for the development, design, Forgejo, PR, team-update and hardware-test guides;
    retains the security, source-of-truth and change-invariant rules.
  • docs/agent-pull-requests.md: new focused guide for WIP/readiness discipline, updating PRs, escalating uncertain
    checklist boxes and completing the evidence appropriate to the change. It links to canonical requirements rather
    than duplicating them.
  • docs/workflow.md: points directly to the team-updates skill instead of a removed AGENTS.md section.

Measurements

Verdict: nothing to measure: documentation only; the game-free checks and resolved Markdown links are the evidence.

Flags and settings

None

Testing

Rebase validation (Windows): this PR @ 1d40b453849e73e6dfe028a9bf0ab7726a2db20a, onto main @ 1c91dafbd627026e59130d5c58290eb028a52348: all 32 relative links/anchors resolve, all 36 PR-description tests pass, and git diff --check passes. The AGENTS.md conflict was resolved by retaining main's newer screenshot requirements in docs/agent-pull-requests.md. No full-suite rerun or game run is claimed; the paired Linux results below are historical evidence for the original revision.

Tested: Linux, game-free:

  • python -I -B tests/run_all.py on this PR @ dbf4f876 and clean main @ aa95d35f: 515 passed, 14 failed, 64 skipped
    on both, with the same failures: test_make_game_cache, test_lift_cleanup_error, test_crash_dialog,
    test_cpm_discovery, test_env_on, test_appimage_player_build, test_options_budget_once, test_linux_preflight,
    test_longshot_ctl, test_pipeline_tour, test_mods_size_table, test_readback_late, test_vk_pgo and test_walk_key.
  • All 31 relative links and anchors in the changed documents resolve.
  • git diff --check passes.
  • Independent GLM 5.3 Flash Standards and Spec reviews; all removed material was found reachable through the new
    references.

Not tested: no game run, because this changes Markdown only and no runtime behavior. No other OS testing is needed
for the same reason.

Must be tested:

  • None

Risks

What could break: an agent could miss a task-specific rule if a pointer were unclear or a link broke. The root
uses explicit task triggers, all changed links were checked, and an independent review verified that removed material
remains reachable.

Turning it off: revert the commit.

Compatibility: Nothing changes: documentation only, with no effect on saves, options, caches, the vk ABI or tools.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Docs updated.
**Type:** docs · **Risk:** low · **Tested on:** Linux, game-free checks · **Needs:** none ## Why Agents load AGENTS.md on every task, but much of it applied only to one-time sign-in or the final pull request and testing stages. Keeping those details in the root file spent attention on irrelevant instructions and made the always-relevant rules harder to find. The open issue tracker was searched; no issue covers this documentation problem. ## What changed The root agent guide now keeps the general rules and task-keyed pointers, while setup, collaboration and pull request details live in their canonical guides. AGENTS.md drops from 1,890 to 511 words without dropping the agent-specific rules; detailed requirements remain in CONTRIBUTING.md and the existing Forgejo guide and skills. - `AGENTS.md`: adds explicit triggers for the development, design, Forgejo, PR, team-update and hardware-test guides; retains the security, source-of-truth and change-invariant rules. - `docs/agent-pull-requests.md`: new focused guide for WIP/readiness discipline, updating PRs, escalating uncertain checklist boxes and completing the evidence appropriate to the change. It links to canonical requirements rather than duplicating them. - `docs/workflow.md`: points directly to the team-updates skill instead of a removed AGENTS.md section. ## Measurements **Verdict:** nothing to measure: documentation only; the game-free checks and resolved Markdown links are the evidence. ### Flags and settings None ## Testing **Rebase validation (Windows):** this PR @ `1d40b453849e73e6dfe028a9bf0ab7726a2db20a`, onto main @ `1c91dafbd627026e59130d5c58290eb028a52348`: all 32 relative links/anchors resolve, all 36 PR-description tests pass, and `git diff --check` passes. The AGENTS.md conflict was resolved by retaining main's newer screenshot requirements in docs/agent-pull-requests.md. No full-suite rerun or game run is claimed; the paired Linux results below are historical evidence for the original revision. **Tested:** Linux, game-free: - `python -I -B tests/run_all.py` on this PR @ dbf4f876 and clean main @ aa95d35f: 515 passed, 14 failed, 64 skipped on both, with the same failures: test_make_game_cache, test_lift_cleanup_error, test_crash_dialog, test_cpm_discovery, test_env_on, test_appimage_player_build, test_options_budget_once, test_linux_preflight, test_longshot_ctl, test_pipeline_tour, test_mods_size_table, test_readback_late, test_vk_pgo and test_walk_key. - All 31 relative links and anchors in the changed documents resolve. - `git diff --check` passes. - Independent GLM 5.3 Flash Standards and Spec reviews; all removed material was found reachable through the new references. **Not tested:** no game run, because this changes Markdown only and no runtime behavior. No other OS testing is needed for the same reason. **Must be tested:** - None ## Risks **What could break:** an agent could miss a task-specific rule if a pointer were unclear or a link broke. The root uses explicit task triggers, all changed links were checked, and an independent review verified that removed material remains reachable. **Turning it off:** revert the commit. **Compatibility:** Nothing changes: documentation only, with no effect on saves, options, caches, the vk ABI or tools. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Docs updated.
Marcuss2 changed title from WIP: docs(agents): disclose setup and pull request guidance to docs(agents): disclose setup and pull request guidance 2026-11-15 15:11:21 +00:00
futondestroyer approved these changes 2026-11-15 17:04:34 +00:00
Dismissed
futondestroyer left a comment

Reviewed the complete three-file diff at dbf4f876d5cc6f39cf1c391fd3e303c17459d0d7 against aa95d35f. No blocking findings. The task-specific pointers preserve access to the removed setup, PR/readiness, team-update and hardware-testing requirements through CONTRIBUTING.md, docs/forge.md, the new focused PR guide and the existing skills. The general safety/source-of-truth rules and renderer/change invariants remain in the root guide. The new guide also preserves the explicit discipline around uncertain checklist boxes, same-session readiness and updating both description and history.

Independent Windows checks: all 31 relative links/anchors in the changed documents resolve; all 36 tests in tests/test_check_pr_description.py pass; git diff --check passes. The reviewed revision's PR-description checker reports complete, with all applicable checklist boxes ticked, and Forgejo reports a clean merge. The older shared checkout's checker uses an obsolete template and was not used for the readiness verdict.

I did not repeat the complete suite, run the game or measure agent behavior/token savings. The author's paired Linux suite results remain their evidence; the documentation-only scope does not need a game run. Approved.

Reviewed the complete three-file diff at dbf4f876d5cc6f39cf1c391fd3e303c17459d0d7 against aa95d35f. No blocking findings. The task-specific pointers preserve access to the removed setup, PR/readiness, team-update and hardware-testing requirements through CONTRIBUTING.md, docs/forge.md, the new focused PR guide and the existing skills. The general safety/source-of-truth rules and renderer/change invariants remain in the root guide. The new guide also preserves the explicit discipline around uncertain checklist boxes, same-session readiness and updating both description and history. Independent Windows checks: all 31 relative links/anchors in the changed documents resolve; all 36 tests in tests/test_check_pr_description.py pass; git diff --check passes. The reviewed revision's PR-description checker reports complete, with all applicable checklist boxes ticked, and Forgejo reports a clean merge. The older shared checkout's checker uses an obsolete template and was not used for the readiness verdict. I did not repeat the complete suite, run the game or measure agent behavior/token savings. The author's paired Linux suite results remain their evidence; the documentation-only scope does not need a game run. Approved.
HumanBean approved these changes 2026-11-15 17:41:18 +00:00
Dismissed
Member

Prepared and checked a rebase onto main 0557080fa82a55dec0abbbd4de0c9eec007cee2c at the user's request. The conflict in AGENTS.md comes from main's newer screenshot-evidence instructions. The resolution keeps the shorter root guide and moves that new screenshot guidance into docs/agent-pull-requests.md, preserving before/after captions, local website builds, both themes, 390px phone coverage, synthetic data and upload guidance. Original capture/game-data restrictions remain intact.

The tested rebased commit is 0ef8ed1d02fccf8a4d744c8483b5221999b62733, available on the user's fork: https://git.magicbean.dev/futondestroyer/Longshot/src/branch/codex/pr818-rebased

Checks after resolving the conflict: all 32 actual relative Markdown links/anchors resolve, all 36 PR-description tests pass, git diff --check passes, and the isolated checkout is clean. No complete-suite rerun or game run is claimed; only documentation differs from the named main.

I could not update this PR's source branch: the source fork reports no push permission for this account, maintainer edits are disabled, and Forgejo's PR update action returned HTTP 403. The PR head therefore remains unchanged; it has not been merged. Please pick up the prepared rebased commit, or enable maintainer edits so this PR can be updated and checked before merge. No replacement PR was opened and no direct push to upstream main was attempted.

Prepared and checked a rebase onto main `0557080fa82a55dec0abbbd4de0c9eec007cee2c` at the user's request. The conflict in AGENTS.md comes from main's newer screenshot-evidence instructions. The resolution keeps the shorter root guide and moves that new screenshot guidance into docs/agent-pull-requests.md, preserving before/after captions, local website builds, both themes, 390px phone coverage, synthetic data and upload guidance. Original capture/game-data restrictions remain intact. The tested rebased commit is `0ef8ed1d02fccf8a4d744c8483b5221999b62733`, available on the user's fork: https://git.magicbean.dev/futondestroyer/Longshot/src/branch/codex/pr818-rebased Checks after resolving the conflict: all 32 actual relative Markdown links/anchors resolve, all 36 PR-description tests pass, git diff --check passes, and the isolated checkout is clean. No complete-suite rerun or game run is claimed; only documentation differs from the named main. I could not update this PR's source branch: the source fork reports no push permission for this account, maintainer edits are disabled, and Forgejo's PR update action returned HTTP 403. The PR head therefore remains unchanged; it has not been merged. Please pick up the prepared rebased commit, or enable maintainer edits so this PR can be updated and checked before merge. No replacement PR was opened and no direct push to upstream main was attempted.
futondestroyer force-pushed docs/agents-progressive-disclosure from dbf4f876d5
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
to 1d40b45384
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 17s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 23s
Third-party parts / As their notes say (pull_request) Successful in 37s
PR description / Description follows the template (pull_request_target) Successful in 14s
2026-11-15 17:48:44 +00:00
Compare
futondestroyer dismissed futondestroyer's review 2026-11-15 17:48:44 +00:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

futondestroyer dismissed HumanBean's review 2026-11-15 17:48:44 +00:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

Member

Rebased onto main 1c91dafb at 1d40b453. Preserved the newer screenshot requirements in the focused PR guide. All 32 relative links/anchors and all 36 PR-description tests pass, with a clean diff. Historical Linux full-suite results remain tied to their original revisions. Maintainer-edit access allowed the exact-head-lease push.

Rebased onto main 1c91dafb at 1d40b453. Preserved the newer screenshot requirements in the focused PR guide. All 32 relative links/anchors and all 36 PR-description tests pass, with a clean diff. Historical Linux full-suite results remain tied to their original revisions. Maintainer-edit access allowed the exact-head-lease push.
futondestroyer left a comment

Rechecked rebased head 1d40b45384 on main 1c91dafb. The conflict resolution preserves the newer screenshot requirements in docs/agent-pull-requests.md. All 32 actual relative links/anchors and all 36 focused PR-description tests pass; git diff --check is clean. No blocking findings. The PR description distinguishes this validation from the historical full-suite evidence.

Rechecked rebased head 1d40b453849e73e6dfe028a9bf0ab7726a2db20a on main 1c91dafb. The conflict resolution preserves the newer screenshot requirements in docs/agent-pull-requests.md. All 32 actual relative links/anchors and all 36 focused PR-description tests pass; git diff --check is clean. No blocking findings. The PR description distinguishes this validation from the historical full-suite evidence.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!818
No description provided.