# 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.
- **Every recommendation cites a session and timestamp.** New scanner rules need a
  `source` matching `Tech Talk 1114xx … m:ss` or `WWDC26 278 … m:ss`; the metadata test
  enforces it.
- **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
  ```