docs: add PR template and stack, verification and platform rules to the agent guide by vonovak · Pull Request #216 · expo/expo-agent-cli

vonovak · 2026-10-27T21:50:25Z

Adds a PR template and extends the package AGENTS.md with rules on stacked PRs, verification, obsolete tests, platform coverage and EAS sessions. Docs only; bun run format:check passed.

🤖 Generated with Claude Code

…m rules to the package guide The root AGENTS.md duplicated the package guide. The package guide now names the gh stack CLI for stacked PRs, asks for observed facts before building on an assumption, tells an upstack PR to delete tests that no longer add confidence, and requires a check on both platforms. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Kudo

from my experience, agents create pr using cli or api that would pass PULL_REQUEST_TEMPLATE.md. you should point out PULL_REQUEST_TEMPLATE.md in AGENTS.md so that agents will read it.
coincidentally i was thinking to add a little section in pr description. something like "Trying to pitch shortly about the pr". example pr #173. not sure if that's useful

Kudo · 2026-10-29T17:37:42Z

 - **Build expected values with the product's helpers.** A test of a platform-specific value (an argv, a path, an escape) builds the expected value with the helper that the code uses.
 - **Build fixtures from one builder.** Give each fixture type one builder that takes overrides, and pass only the fields that differ, for example `makeLock({ pid: 4242 })`. Then a new field is a one-file change.
+- **Test both platforms.** When a change touches behavior that runs on iOS and Android, test it on both. A pass on one platform proves nothing about the other.
+- **EAS simulator sessions are usually free here.** This repo is developed by Expo employees, so start an EAS simulator session or a live cloud run when a check needs one, without asking. Do not abuse them, but do not be afraid to use them. Stop the session when you finish.


[bug] "Usually free" and "start an EAS simulator session or a live cloud run … without asking" contradict the billing contract agents are also told to follow. llp/0015-backend-selection-and-config.rfc.md:67 says an EAS Simulator session (eas simulator) costs credits from the moment it starts, and only after a person chose --eas or deviceBackend: "eas". llp/0022-live-tier.plan.md:58 says a tier that can bill money must be asked for by name, and :267-269 gates live-cloud on AGENT_CLI_LIVE_CLOUD=1 so a machine that already has the other prerequisites does not start a billing session by accident. e2e-live/RUNBOOK.md:40 and :266 require both AGENT_CLI_LIVE_EAS=1 and AGENT_CLI_LIVE_CLOUD=1, a login with expo-ci access (not a human account), and label bun run test:live:cloud as billing a cloud session. .eas/workflows/agent-cli-cloud-e2e.yml:12-16 already runs that suite on every PR: each job that reaches a session bills one, four billed sessions per push. A session that never becomes ready is still billed (e2e-live/__tests__/live-cloud-test.ts cost note; llp/0022 cleanup section). Public EAS pricing is the same shape: paid plans include 60 simulator minutes a month, then $0.10 per minute, billed per second. An agent that treats this as free and skips the ask will start extra sessions, often on the ambient Expo login rather than expo-ci, and the next bullet ("test both platforms") makes two of them the default.

Suggestion: Drop "usually free" and "without asking." Say a check may start a session only when the local or stub suite cannot answer it, on the expo-ci account, with AGENT_CLI_LIVE_EAS=1 and AGENT_CLI_LIVE_CLOUD=1 (or an explicit dev --<platform> --eas the person already chose). Point at bun run test:live:cloud from packages/@expo/agent-cli after bun run build. Say CI may already have billed the four cloud jobs, so do not start another unless that evidence is missing. Stop the session before finishing (dev:stop --eas or the suite's afterAll); a failed start still needs simulator:stop.

Took the suggestion. The bullet now says a change to the EAS path is proven only on EAS, that a session bills from start (llp/0015), that it starts only through the opt-ins on expo-ci after the local or stub suites cannot answer, that CI already bills four sessions per push, and how to stop it, including a failed start.

Kudo · 2026-10-29T17:37:43Z


 ## Pull requests

+- This repo uses GitHub stacks. Manage stacked PRs with the `gh stack` CLI: `gh stack init`, `add`, `submit`, `sync` and `rebase`. Do not build a stack from hand-pushed branches.


[suggestion] gh stack init, add, submit, sync, and rebase are real subcommands of the github/gh-stack extension, and scripts/stack-gate.ts waits on the base-branch chain gh stack submit creates. Stock gh does not ship stack (gh extension list shows github/gh-stack). The same bullet forbids hand-pushed branches, so a checkout without the extension has no allowed way to open a stack and fails with an unknown command.

Suggestion: Name the prerequisite next to the commands: gh extension install github/gh-stack (GitHub CLI 2.0+ and Git 2.36+). Keep the ban on hand-pushed stacks once that path exists.

Added the install line with the GitHub CLI 2.0+ and Git 2.36+ requirement, plus the gh-stack agent skill (gh skill install github/gh-stack) with a link. The ban on hand-pushed stacks stays.

…skill The pitch lives in the Feature prompt of the template. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vonovak · 2026-10-29T19:14:49Z

Thanks. AGENTS.md now points at the PR template and says to fill it in also when a CLI or an agent opens the PR. The pitch is in the template: the Feature prompt asks for two or three sentences on what agents can now do and why. The root AGENTS.md and the research notes are gone; the four rules live in the package guide.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vonovak added 2 commits October 27, 2026 22:50

docs: add focused pull request template

4cdc0fc

docs: refine contribution guidance from AI-assisted projects

98fc616

vonovak changed the title ~~docs: add focused pull request template~~ docs: add PR template and repository agent guidance Oct 27, 2026

vonovak and others added 2 commits October 28, 2026 08:00

docs: frame feature descriptions around agents

5029f00

vonovak changed the title ~~docs: add PR template and repository agent guidance~~ docs: add PR template and stack, verification and platform rules to the agent guide Oct 29, 2026

vonovak and others added 6 commits October 29, 2026 10:53

docs: drop the PR template research notes

95afe3f

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: the obsolete-test rule applies to every PR, not only stacks

7a6567b

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: one bullet for obsolete tests, with the stack case as emphasis

b461f08

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: drop "not earlier" from the stack test rule

9249320

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: EAS simulator sessions are usually free for this repo's developers

3a42bf4

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: do not abuse EAS sessions, but do not be afraid to use them

e3bfd3c

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vonovak marked this pull request as ready for review October 29, 2026 10:28

vonovak requested a review from Kudo October 29, 2026 17:31

Kudo requested changes Oct 29, 2026

View reviewed changes

vonovak and others added 2 commits October 29, 2026 19:48

docs: point agents at the PR template and the gh-stack extension and …

6bc3d5a

…skill The pitch lives in the Feature prompt of the template. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs: check the EAS path on EAS, through the billing opt-ins

b122f29

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vonovak requested a review from Kudo October 29, 2026 19:14

docs: drop the gh and git version note from the stack bullet

181b1d6

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Kudo approved these changes Oct 29, 2026

View reviewed changes

vonovak merged commit af98e86 into main Oct 29, 2026
16 of 18 checks passed

vonovak deleted the codex/pr-template branch October 29, 2026 19:32

Navigation Menu

Repository navigation

docs: add PR template and stack, verification and platform rules to the agent guide - #216

docs: add PR template and stack, verification and platform rules to the agent guide#216
vonovak merged 13 commits into
mainfrom
codex/pr-template

vonovak commented Oct 27, 2026 •

edited

Loading

Uh oh!

Kudo left a comment

Uh oh!

Kudo Oct 29, 2026

Uh oh!

vonovak Oct 29, 2026

Uh oh!

Kudo Oct 29, 2026

Uh oh!

vonovak Oct 29, 2026

Uh oh!

vonovak commented Oct 29, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Pull requests

		- This repo uses GitHub stacks. Manage stacked PRs with the `gh stack` CLI: `gh stack init`, `add`, `submit`, `sync` and `rebase`. Do not build a stack from hand-pushed branches.

Conversation

vonovak commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kudo left a comment

Choose a reason for hiding this comment

Uh oh!

Kudo Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

vonovak Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

Kudo Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

vonovak Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

vonovak commented Oct 29, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vonovak commented Oct 27, 2026 •

edited

Loading