# Apple Agent Kit
Proof-driven macOS and iOS automation for coding agents.
Apple Agent Kit gives Codex, Claude Code, and CI reusable playbooks, dry-run scripts, GitHub Actions templates, schemas, and privacy-safe evidence rules for Apple app repos. The public kit owns the generic automation contracts; private adapters supply projects, schemes, runner labels, devices, signing, fixture commands, and evidence policy.
Start with eligibility. Promote only when the proof is clean.
## Start Here
```bash
git clone https://github.com/neonwatty/apple-agent-kit.git
cd apple-agent-kit
python3 scripts/validate-release.py
python3 scripts/aak.py inspect --repo . --adapter templates/adapter.example.json --json
python3 scripts/aak.py render-workflows --adapter templates/adapter.example.json --output /tmp/aak-render --force
```
See [Install and Reuse](docs/install.md) for Codex and Claude Code validation paths, including local plugin validation and source-checkout testing.
## What It Enables
| Stage | Use it for | Public safety boundary |
| --- | --- | --- |
| Intake | Inspect an Apple repo and choose relevant automation tracks. | Read-only; no device, runner, app, or account actions. |
| Adapter validation | Check the private adapter shape before running workflows. | Real project, signing, runner, bundle, and device values stay outside this repo. |
| Workflow rendering | Render reusable GitHub Actions workflows into scratch space for review. | Rendering is dry-run oriented and reports no physical-device actions. |
| macOS and iOS eligibility | Prove a repo can consume AAK before product automation. | No product build/test, app launch, screenshots, WDA, simulator boot, or physical-device work. |
| Fixture UI smoke | Promote to deterministic GUI proof against sterile fixture apps, demo modes, or test-only surfaces. | Manual dispatch, exact approval input, validated receipts, adapter allowlisted artifacts only. |
| `xcresult` proof | Assert the expected XCTest or UI smoke method actually appeared in result-bundle output. | Emits sanitized counts and assertion results, not raw bundle internals. |
| Runner health | Check self-hosted Mac runner readiness. | Runner labels and host details stay private; no product or device work. |
| Manual remote PR session | Request exact-SHA work from a private Mac through a pull-based artifact contract. | Public workflow creates a validated request only; private adapters decide what runs. |
| iOS physical device | Manually prepare an approved preview-device readiness or smoke run through a private adapter. | Requires exact approval input and private approval reference; no device identifiers, raw inventories, screenshots, or app data in public evidence. |
## Proof-Backed Adoption
Current public proof records show the eligibility path working across macOS and iOS app repos, plus the first sanitized manual remote PR session proof:
- [Foil macOS CI Eligibility Proof](docs/proof-records/foil-macos-ci-eligibility-2026-06-25.md)
- [Foil iOS CI Eligibility Proof](docs/proof-records/foil-ios-ci-eligibility-2026-06-25.md)
- [PRCard iOS CI Eligibility Proof](docs/proof-records/prcard-ios-ci-eligibility-2026-06-27.md)
- [PRCard Manual Remote PR Session Proof](docs/proof-records/prcard-manual-remote-pr-session-2026-06-29.md)
- [PRCard iOS Physical-Device Readiness Proof](docs/proof-records/prcard-ios-physical-readiness-2026-07-05.md)
For the source-backed capability map, adoption summary, next-step recommendation, and landing-page plan, see [Apple Agent Kit Positioning And Landing Page Plan](docs/positioning-and-landing-page.md).
## Public And Private Split
This public repo contains reusable patterns only:
- skills and agent playbooks;
- dependency-free scripts;
- workflow templates;
- adapter and receipt examples;
- schemas;
- privacy-safe evidence rules;
- sanitized proof records.
Private adapters belong in app repos or secrets. They provide concrete project paths, schemes, bundle identifiers, signing values, runner labels, device choices, fixture commands, and screenshot/evidence policy.
## Repository Shape
- `.codex-plugin/plugin.json` - Codex plugin manifest.
- `.claude-plugin/plugin.json` - Claude Code plugin manifest.
- `skills/` - Agent-facing playbooks.
- `docs/` - Design, adapter contract, evidence policy, and operating notes.
- `scripts/` - Generic helper scripts that must not contain app-specific values.
- `templates/` - Reusable workflow and config templates.
## Install And Validate
Apple Agent Kit v0 is source-first. Start with:
```bash
git clone https://github.com/neonwatty/apple-agent-kit.git
cd apple-agent-kit
python3 scripts/validate-release.py
```
## v0 Commands
The v0 command surface is dependency-free Python and dry-run oriented:
```bash
python3 scripts/aak.py inspect --repo . --adapter templates/adapter.example.json --json
python3 scripts/aak.py validate-adapter templates/adapter.example.json
python3 scripts/aak.py render-workflows --adapter templates/adapter.example.json --output /tmp/aak-render --force
python3 scripts/aak.py check-xcode --json
python3 scripts/aak.py check-xcode --adapter templates/adapter.example.json --platform ios --json
python3 scripts/aak.py summarize-xcresult path/to/TestResults.xcresult --json
python3 scripts/aak.py assert-xcresult --summary-json templates/xcresult-summary.example.json --expect-test testFixtureViewAppears --require-success --json
python3 scripts/aak.py prepare-fixture-ui-smoke --adapter templates/adapter.example.json --script /tmp/aak-fixture-smoke.sh --approval fixture-ui-smoke --json
python3 scripts/aak.py prepare-fixture-ui-smoke --adapter templates/adapter.example.json --script /tmp/aak-ios-fixture-smoke.sh --approval fixture-ui-smoke --platform ios --json
bash templates/fixture-ui-smoke-command.example.sh
python3 scripts/aak.py validate-fixture-ui-smoke-receipt templates/fixture-ui-smoke.receipt.example.json --json
python3 scripts/aak.py validate-fixture-ui-smoke-receipt templates/ios-simulator-fixture-ui-smoke.receipt.example.json --json
python3 scripts/aak.py hash-artifact artifacts/fixture-ui-smoke/fixture.log --json
python3 scripts/aak.py prepare-ios-physical-device --adapter templates/adapter.example.json --script /tmp/aak-ios-physical-device.sh --approval ios-physical-device --approval-ref example-approval-001 --mode readiness --json
python3 scripts/aak.py validate-ios-physical-device-receipt templates/ios-physical-device.receipt.example.json --json
python3 scripts/aak.py prove-ios-physical-adopter --adapter templates/adapter.example.json --repo . --json
python3 scripts/aak.py validate-manual-remote-job templates/manual-remote-pr-session.job-request.example.json --json
python3 scripts/aak.py validate-manual-remote-receipt templates/manual-remote-pr-session.receipt.example.json --json
```
These commands do not install apps, boot simulators, start WDA, launch host apps, dispatch CI workflows, or touch physical devices.
The rendered workflow set includes eligibility, fixture, runner-health, manual remote, and gated physical-device templates:
- `macos-runner-health.yml` checks a specific Mac runner on demand.
- `macos-ci-eligibility.yml` validates a private adapter, renders reusable workflows into scratch space, and checks Xcode readiness without building or testing the product.
- `macos-fixture-ui-smoke.yml` manually runs a private sterile fixture smoke command, removes stale receipts, validates its receipt and listed artifact hashes, and uploads only receipt-validated allowlisted evidence, including failure evidence when the private command writes a valid failed receipt during that run.
- `ios-ci-eligibility.yml` validates a private iOS adapter, renders reusable workflows into scratch space, checks Xcode readiness, and inventories simulators without building, testing, booting, installing, launching, screenshotting, or touching physical devices. Use `check-xcode --adapter <adapter> --platform ios --require-simulator-destination --json` when an adoption proof should fail on an unavailable configured simulator destination.
- `ios-simulator-fixture-ui-smoke.yml` manually runs a private sterile simulator fixture command, removes stale receipts, validates its receipt and listed artifact hashes, and uploads only receipt-validated allowlisted evidence, including failure evidence when the private command writes a valid failed receipt during that run.
- `ios-physical-device.yml` manually prepares a private physical-device readiness or smoke command, requires the exact `ios-physical-device` approval input plus a private approval reference, can require same-dispatch device-lab health success before the selected physical command is prepared, validates the sanitized receipt and listed artifact hashes, and uploads only receipt-validated allowlisted evidence.
Bind the self-hosted Mac lanes with private `ci.macosRunnerLabels`; keep physical iPhone workflows behind a separate approval gate.
For the first real GUI proof after eligibility, use `macos-fixture-ui-smoke` or `ios-simulator-fixture-ui-smoke` with a private `automation` adapter block. The public kit provides the generic receipt shape in `templates/fixture-ui-smoke.receipt.example.json`, the iOS example in `templates/ios-simulator-fixture-ui-smoke.receipt.example.json`, and a copyable command scaffold in `templates/fixture-ui-smoke-command.example.sh`; private repos supply the fixture app, smoke command, log subsystem, and evidence allowlist.
Use `hash-artifact` from private smoke scripts when writing receipt artifact metadata. File artifacts use normal SHA-256. Directory artifacts such as `.xcresult` bundles use an AAK manifest hash over sorted contained file paths, file sizes, and file hashes, so the public receipt can prove the bundle without publishing raw bundle internals. In CI, fixture workflows upload only receipt artifacts that pass hash verification and match the adapter `allowedArtifactGlobs`.
Use `assert-xcresult` after Xcode test runs to turn the result bundle into a proof: require a passing status, assert the expected XCTest or UI smoke method appeared in `xcresulttool` output, and emit only sanitized counts and assertion results. Expected tests may be method names like `testFixtureViewAppears` or full XCTest identifiers like `FixtureUITests/FixtureUITests/testFixtureViewAppears`; matching is exact on path components, not loose substrings. The command accepts either `--path path/to/TestResults.xcresult` for live CI or `--summary-json` for sterile parser fixtures and saved parser input.
See [Adopting the macOS CI Eligibility Lane](docs/adopting-macos-ci-eligibility.md), [Adopting macOS Fixture UI Smoke](docs/adopting-macos-fixture-ui-smoke.md), [Adopting the iOS CI Eligibility Lane](docs/adopting-ios-ci-eligibility.md), [Adopting iOS Simulator Fixture UI Smoke](docs/adopting-ios-simulator-fixture-ui-smoke.md), [Self-Hosted Runner Scope and Onboarding](docs/self-hosted-runner-scope-onboarding.md), the [Dedicated Mac Runner-Health Checklist](docs/dedicated-mac-runner-health-checklist.md), and the [Private Adapter Rollout Checklist](docs/private-adapter-rollout-checklist.md) for a repeatable public/private adoption path. Public proof records are indexed in [Proof Records](docs/proof-records/index.md).
For approved preview-device work, start with [Adopting iOS Physical Device](docs/adopting-ios-physical-device.md). The first reusable rung is device-lab health plus readiness proof: prove the shared lab is alive, resolve the approved device, check lock/readiness and Automation Mode, and emit sanitized receipts without app install, launch, WDA/Appium, screenshots, or raw inventories. Physical-device adapters must pin `ci.appleAgentKitRef` to a reviewed AAK commit and use opaque sanitized approval references. Promote to physical smoke only after lab-health and readiness receipts are repeatable.
Use `prove-ios-physical-adopter` before copying rendered workflows into a private iOS repo. In default mode it validates the adapter, renders workflows into scratch space, and asserts the lab-health gate without touching devices. With `--run-private`, it runs the private lab-health and selected physical command only after an opaque approval reference is provided.
For manually requested remote Mac checks from a PR, see [Manual Remote PR Session](docs/manual-remote-pr-session.md). The public workflow only emits a validated pull-queue job request; private adapters decide which host accepts it, which commands run, whether an app launch is allowed, and whether a local Codex-assisted manual testing session is created.
For PR closeout review, see [Slim Codex Autoreview](docs/slim-codex-autoreview.md) and the `codex-autoreview` skill. The design keeps review Codex-native, scope-limited, and advisory.
For release gating, use [v0 Release Readiness](docs/v0-release-readiness.md).
## Private Adapters
Private adapters provide concrete values for a repo:
- project or workspace path
- scheme names
- bundle identifiers
- UI test targets
- runner labels
- device names
- signing and secret variable names
- sterile fixture UI smoke command and log subsystem
- allowed screenshot/evidence policy
See [docs/adapter-contract.md](docs/adapter-contract.md).
## Status
This repo is at v0 dry-run stage. Physical runner and iPhone workflows should be validated only through private adapters, manual dispatch, exact approval input, and explicit private approval references.