docs(agents): disclose setup and pull request guidance #818
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!818
Loading…
Reference in a new issue
No description provided.
Delete branch "Marcuss2/Longshot:docs/agents-progressive-disclosure"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 uncertainchecklist 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, andgit diff --checkpasses. 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.pyon this PR @ dbf4f876 and clean main @aa95d35f: 515 passed, 14 failed, 64 skippedon 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.
git diff --checkpasses.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:
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
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.WIP: docs(agents): disclose setup and pull request guidanceto docs(agents): disclose setup and pull request guidanceReviewed 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.
Prepared and checked a rebase onto main
0557080fa82a55dec0abbbd4de0c9eec007cee2cat 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-rebasedChecks 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.
dbf4f876d51d40b45384New commits pushed, approval review dismissed automatically according to repository settings
New commits pushed, approval review dismissed automatically according to repository settings
Rebased onto main
1c91dafbat1d40b453. 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.Rechecked rebased head
1d40b45384on main1c91dafb. 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.