AGENTS.md git:20261029.170b743A

Immutable. This exact content never changes and is served at /api/v1/blob/ec3c46de348d6443.

# Agent guidance

This repository contains Agent Skills that advise on and change iOS app code.

- **Phase 1 stays read-only.** `duo_scan.py` and `sdk_api_check.py` must never write to
  the scanned project or the SDK. Keep it that way; `test_scan_does_not_modify_files`
  guards the scanner.
- **`duo_pose.py` changes simulator state** — it moves an iPhone Duo simulator's hinge
  and device orientation through the third-party `hinge` CLI. Skills run it only in the verification phase,
  after the developer approves; it acts on iPhone Duo simulators only and restores the
  angle and the orientation after `shoot`. Its tests never touch a simulator.
- **Every recommendation cites a session and timestamp.** New scanner rules need a
  `source` matching `Tech Talk 1114xx … m:ss` or `WWDC26 278 … m:ss`.
  Where no session covers a rule, an Apple technote (`TN3208 …`) is the source;
  the metadata test enforces both forms.
  An Apple engineer's forum answer is cited by thread number (`Forums 848036`) in the
  skills and references, never as a scanner rule's only source; it ranks below the
  talks, the HIG, the documentation and the SDK (`references/sources.md`).
- **The SDK outranks the talks.** Typecheck every code sample against the installed
  SDK before adding it (`xcrun --sdk iphonesimulator swiftc -typecheck`). The iOS 27.1
  SDK ships with Xcode 27.1, so "reproduced from a session page" is no longer reason
  enough for a 27.1 API. A sample that cannot be typechecked must say so, and say why —
  that it is a fragment, or that the machine lacks the SDK.
- **Shared files have one source.** Edit `references/*.md` and `scripts/*.py` at the
  root, then run `python3 scripts/sync_skill_copies.py`. Never edit the copies under
  `skills/*/references` or `skills/*/scripts` that the sync script owns.
- **Keep SKILL.md descriptions under 1024 characters** and the `name` equal to the
  directory name.
- **Scanner changes need tests** for both a positive and a negative case.
- **Behavior changes need evals.** Each skill keeps skill-creator evals in
  `skills/<skill>/evals/` (`evals.json` with fixture projects under `files/`, and
  `trigger-evals.json`). Re-run them with and without the skill before claiming an
  improvement; `scripts/package_skills.py` leaves `evals/` out of release archives.
- Keep the plugin version identical in `.claude-plugin/plugin.json`,
  `.claude-plugin/marketplace.json`, `.cursor-plugin/plugin.json` and
  `agents/openai.yaml`. A GitHub release is cut by pushing a matching `vX.Y.Z` tag;
  the `Release` workflow builds the `.skill` archives (`CONTRIBUTING.md` › Releasing).
- Run before completing a change:

  ```bash
  python3 scripts/sync_skill_copies.py --check
  python3 -m unittest discover -s tests -v
  ```