chore(agents): add AGENTS.md with best-practices fetch and testing policy

[albertoelias-crossmint]

Description

Connects this repo to Paella-Labs/best-practices, the central source of truth for how we write and review code (code, testing, documentation, deployments, operations). Agents follow it when they write code here, and Devin checks changes against it in review. Greptile enforces the same repo through its own config.

• AGENTS.md is the agent-agnostic entry point. At session start it runs ./scripts/fetch-best-practices.sh typescript.md and follows the result. For PR reviews it adds: "check changes against the fetched best-practices doc and cite the specific rule when flagging".
• scripts/fetch-best-practices.sh is the same file in every consumer (canonical copy: crossbit-main). It fetches every file in best-practices manifest.txt (all required), then the stack files passed as arguments (skipped on 404). The result is cached under ${XDG_CACHE_HOME:-~/.cache}/paella-best-practices/, keyed by commit SHA and stack list, and GitHub is checked at most every 24h. If a refresh fails, the script serves a cache only when it was built for the same stack list. It never exits 0 with a partial doc. A cache from the previous ~/.claude fetcher is still printed, but it exits 1 unless it is the old all-files snapshot and contains the requested stacks.
• Adds AGENTS.md (the repo had none): purpose, pnpm/turbo/biome commands, and unit-test commands. CLAUDE.md imports it with @AGENTS.md.
• .claude/settings.json adds an optional SessionStart hook that runs the same script. .gitignore now ignores only .claude/settings.local.json instead of all of .claude, so shared agent config is committed.
• Testing section (the testing addon): points to root test-conventions.md for naming, BDD structure, tags and folders. The default evidence is the Playwright report from the apps/wallets/quickstart-devkit POM tests, plus a recorded run against the staging sandbox. It states that the E2E-first policy applies to new code, that existing suites stay, and which artifact to link in the PR as evidence the feature works.

Gap: the Playwright config keeps video only when a test fails, so recording every run needs a config change (follow-up).

Pairs with https://github.com/Paella-Labs/best-practices/pull/25. Until that merges, best-practices main has no manifest.txt, so the script falls back to fetching every .md file there, and stack files are skipped as 404s.

Test plan

bash -n passes. I ran the script against a fake gh that serves the best-practices PR branch. These scenarios passed: complete fetch; a required manifest file returning 404 (cold, and with a last good cache); an optional stack returning 404; no manifest upstream; offline with a matching, mismatched or missing cache; a transient content failure; each legacy cache format (the old all-files snapshot with and without the requested stack, keyed, root-generated, unrecognized); a manifest entry also passed as an argument; filenames containing spaces; 10 concurrent runs; an unwritable cache dir.

Package updates

None (no package code changed, so no changeset).

Link to Devin session: https://crossmint.devinenterprise.com/sessions/7983bb75c26246418063bfe0d695e3c1
Open in Devin Desktop: https://crossmint.devinenterprise.com/desktop/session/7983bb75c26246418063bfe0d695e3c1?variant=devin
Requested by: @albertoelias-crossmint

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access that start with 'Devin'.

• Disable automatic comment, CI, and merge conflict monitoring

---

Original prompt from Alberto Elias

Extends the existing parallel plan with two additions — fold into the same workstreams:

1. Greptile coverage (new Workstream 6, independent)

   • Copy the best-practices compliance rule from Paella-Labs/crossbit-main/greptile.json (the "Our engineering best practices are documented at..." entry) into a greptile.json / .greptile.json in every repo where Greptile is installed: crossmint-sdk, universal-checkout, open-signer, crossmint-kotlin-sdk, crossmint-flutter-sdk, crossmint-swift-sdk, solana-smart-account, stellar-smart-account, smart-wallet-modules, lobster.cash, devin-tools, paella-os. Repos that don't use Greptile can skip the file.
   • First verify whether Paella-Labs/best-practices is public — if private, Greptile can't fetch the URL, so either (a) make the repo public (it contains no secrets by design), or (b) inline the short testing policy verbatim in each greptile.json rule instead of linking. Prefer (a); document the choice in best-practices/README.md.
   • Add one testing-specific greptile rule per repo, adapted from crossbit-main's apps/**/libraries/** rule: reviewers should flag missing E2E artifacts and unit-tests-written-after-code on new changes only (incremental improvement, not retroactive enforcement).

2. Artifact defaults (fold into existing workstreams 1, 3, 4, 5)

   • best-practices/core.md: expand the E2E bullet with the definition — "a self-contained output of the E2E run that lets a reviewer confirm the feature works without re-running it: captures evidence of what the system did, not just a pass/fail exit code. Each repo's AGENTS.md names its default artifact."
   • Each repo workstream adds one line to that repo's AGENTS.md under the testing section, per the defaults table: playwright report+trace for TS web/API repos; emulator/simulator report+recording for mobile SDKs; devnet/testnet tx signature for the smart contract repos (using deterministic seeds); CLI transcript/snapsho... (539 chars truncated...)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2244eab

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[greptile-apps]

[Low risk] Adds documentation and a helper script for development guidance.

The PR should not merge until fetch failures stop silently leaving sessions without the required best-practices rules.

_{Reviews (1) · Last reviewed commit: "chore(agents): add Claude Code SessionSt..."}

[devin-ai-integration]

Devin Review found 1 new potential issue.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)