apple-agent-kit 2.0.0 → 2.3.0

package/README.md

@@ -5,7 +5,7 @@
 [![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-blue)](CHANGELOG.md)
 
 Status: Stable
-Version: 2.0.0
+Version: 2.3.0
 
 ## Overview
 
@@ -35,6 +35,8 @@ npx apple-agent-kit
 
 This adds this repository as a Claude Code plugin marketplace and installs the `apple-agent-kit` plugin, so its Skills, Knowledge Contracts, and routing become available inside Claude Code sessions. Requires the `claude` CLI to already be installed.
 
+Codex CLI users: the same installer detects `codex` and prints install instructions instead of erroring. See [.codex/INSTALL.md](.codex/INSTALL.md) for the plugin-marketplace command and a manual clone-and-symlink fallback.
+
 ## Architecture
 
 Apple Documentation
@@ -47,23 +49,31 @@ Skills
 ↓
 Workflows
 
+## Workflows
+
+A Workflow composes several Skills into one task that no single domain owns. Routing matches Workflows first: if the task spans more than one of the Skills a Workflow names, that Workflow is loaded and sequences them; otherwise exactly one Skill is loaded.
+
+- **`authentication`** — Build a sign-in feature end to end: wording, form accessibility, Sign in with Apple, biometric re-auth, Keychain storage. → [WORKFLOW.md](workflows/authentication/WORKFLOW.md)
+- **`app-store-submission`** — Review-guideline compliance and privacy declaration, gated ahead of signing, archive, and export. → [WORKFLOW.md](workflows/app-store-submission/WORKFLOW.md)
+- **`add-widget`** — Widget surface, its configuration and interaction intents, and the background refresh that keeps its timeline current. → [WORKFLOW.md](workflows/add-widget/WORKFLOW.md)
+
 ## Skills
 
 Skills route a task to the minimum set of Knowledge Contracts it needs. Invoke them with a specific task, not a broad topic request — name the concrete thing you're doing (e.g. "check this screen's layout against HIG"), not "tell me about HIG."
 
-- **`authentication`** — Sign-in, sign-up, credential, and biometric implementation. → [SKILL.md](skills/authentication/SKILL.md)
 - **`style-guide`** — UI copy and wording: labels, error text, capitalization, formatting. → [SKILL.md](skills/style-guide/SKILL.md)
 - **`human-interface-guidelines`** — Visual design: layout, color, typography, dark mode, motion, icons. → [SKILL.md](skills/human-interface-guidelines/SKILL.md)
 - **`human-interface-guidelines-components`** — HIG Components/Inputs: lists, buttons, sheets, alerts, navigation, pickers, gestures. → [SKILL.md](skills/human-interface-guidelines-components/SKILL.md)
 - **`human-interface-guidelines-patterns`** — HIG Patterns: onboarding, search, settings, notifications, feedback, undo/redo. → [SKILL.md](skills/human-interface-guidelines-patterns/SKILL.md)
-- **`app-store-review-guidelines`** — App Store submission compliance: metadata, IAP, privacy manifest, spam/duplicate. → [SKILL.md](skills/app-store-review-guidelines/SKILL.md)
-- **`swiftui`** — SwiftUI view composition, navigation, layout, state management. → [SKILL.md](skills/swiftui/SKILL.md)
+- **`app-store-review-guidelines`** — App Store submission compliance: safety, metadata, IAP, privacy, intellectual property, ratings. → [SKILL.md](skills/app-store-review-guidelines/SKILL.md)
+- **`swiftui`** — SwiftUI view composition, navigation, layout, state management, and legacy-code migration. → [SKILL.md](skills/swiftui/SKILL.md)
 - **`swiftui-interaction`** — SwiftUI animation and gestures. → [SKILL.md](skills/swiftui-interaction/SKILL.md)
-- **`accessibility`** — Accessibility API (labels, traits, Dynamic Type, VoiceOver, audits) across SwiftUI/UIKit. → [SKILL.md](skills/accessibility/SKILL.md)
+- **`accessibility`** — Accessibility API (labels, traits, Dynamic Type, VoiceOver, announcements, audits) across SwiftUI/UIKit. → [SKILL.md](skills/accessibility/SKILL.md)
 - **`uikit`** — UIKit screen scaffolding: view controllers, Auto Layout, navigation, diffable views. → [SKILL.md](skills/uikit/SKILL.md)
+- **`uikit-interaction`** — UIKit gestures, animation, view controller transitions, and SwiftUI interop. → [SKILL.md](skills/uikit-interaction/SKILL.md)
 - **`sf-symbols`** — SF Symbols rendering, variants, and configuration across SwiftUI/UIKit. → [SKILL.md](skills/sf-symbols/SKILL.md)
-- **`networking`** — URLSession async/await networking and Codable decoding. → [SKILL.md](skills/networking/SKILL.md)
-- **`xcode`** — Xcode project configuration: build settings, signing, entitlements, archive/export. → [SKILL.md](skills/xcode/SKILL.md)
+- **`networking`** — URLSession networking across async/await, completion-handler, and Combine, plus delegates, background transfers, and TLS trust. → [SKILL.md](skills/networking/SKILL.md)
+- **`xcode`** — Xcode project configuration: build settings, signing, entitlements, archive/export, test plans and coverage, project localization. → [SKILL.md](skills/xcode/SKILL.md)
 - **`local-authentication`** — Face ID/Touch ID implementation. → [SKILL.md](skills/local-authentication/SKILL.md)
 - **`app-tracking-transparency`** — App Tracking Transparency / IDFA authorization. → [SKILL.md](skills/app-tracking-transparency/SKILL.md)
 - **`usernotifications`** — UserNotifications framework: local/push scheduling, delegate handling, actions. → [SKILL.md](skills/usernotifications/SKILL.md)
@@ -82,15 +92,17 @@ Skills route a task to the minimum set of Knowledge Contracts it needs. Invoke t
 - **`core-data`** — Core Data model definition, fetching, relationships. → [SKILL.md](skills/core-data/SKILL.md)
 - **`combine`** — Combine publishers/subscribers, `@Published`, operators. → [SKILL.md](skills/combine/SKILL.md)
 - **`testing`** — XCTest, Swift Testing, and XCUITest implementation. → [SKILL.md](skills/testing/SKILL.md)
+- **`localization`** — String Catalogs, plurals, `Locale` resolution, RTL APIs. → [SKILL.md](skills/localization/SKILL.md)
+- **`core-location`** — Location authorization, delivery, accuracy, background monitoring. → [SKILL.md](skills/core-location/SKILL.md)
+- **`photos`** — Photo library access, pickers, the limited library, fetching, image requests, saving. → [SKILL.md](skills/photos/SKILL.md)
 
 Full routing tables: [skills/index.md](skills/index.md). Domain build order and scope: [docs/architecture/domain-map.md](docs/architecture/domain-map.md).
 
 ## What's New
 
-- 2026-08-07 — Added `testing` Skill (`XCTestCase` structure and assertions, Swift Testing fundamentals, parameterized and async tests, UI testing with `XCUIApplication`, expectations for asynchronous code; curated v1 subset of XCTest/Swift Testing/XCUITest, not exhaustive) — 5 Knowledge Contracts. Sixteenth Tier 2 domain. Two clean, proactively-scoped handoffs rather than discovered conflicts: Xcode Test Plans/code coverage config remain `xcode`'s territory, and `performAccessibilityAudit()` remains `accessibility`'s territory. Corrects several natural-but-wrong assumptions: `setUp()`/`tearDown()` has a same-named once-per-class `class func` overload distinct from the per-test instance methods; `XCUIApplication`/`XCUIElement` are now documented under the XCUIAutomation framework, not XCTest; the `app.buttons["x"]`-style subscript matches any of an element's identifying properties, not only `accessibilityIdentifier`; `@Test(arguments:)` over two bare collections produces a Cartesian product while a `zip`-wrapped single argument produces paired invocations; and `wait(for:timeout:)` is guided-away-from in favor of `await fulfillment(of:timeout:)`, not deprecated. Performance testing, snapshot testing, UI test recording, and mocking/DI patterns remain out of scope.
-- 2026-08-07 — Added `combine` Skill (publishers and subscribers, `@Published`/`ObservableObject`, subjects, transforming/combining operators, assign and memory management; Combine framework API v1) — 5 Knowledge Contracts. Fifteenth Tier 2 domain, resolving the `swiftui`/`combine` state-management boundary this repo had left open pending `combine`'s build. No corrections to the approved scope beyond citation-precision notes (the full `debounce(for:scheduler:options:)` signature, and citing `Publishers.Merge`'s type page for `merge(with:)`). Async/await interop, custom `Publisher`/`Subscriber` conformances, backpressure, and SwiftData/Core Data interop remain out of scope.
-- 2026-08-06 — Added `core-data` Skill (model definition, persistent container setup, managed object context CRUD, fetching with `NSFetchRequest`, relationships and delete rules; Core Data framework API v1) — 5 Knowledge Contracts. Fourteenth Tier 2 domain, closing the persistence seam left open by `swiftdata`. Corrects a natural-but-wrong assumption: `NSDeleteRule`'s case names carry a `DeleteRule` suffix (`.cascadeDeleteRule`/`.nullifyDeleteRule`/`.denyDeleteRule`/`.noActionDeleteRule`), distinct from SwiftData's shorter `.cascade`/`.nullify`/`.deny`/`.noAction` spellings for the same four concepts. CloudKit sync, migration, `NSFetchedResultsController`, and SwiftData interop remain out of scope.
-
+- 2026-08-23 — Codex CLI support landed. This repo's Skills are now loadable from OpenAI's Codex CLI, not just Claude Code, with zero changes to any Knowledge Contract, Skill, Reference, or Workflow — Codex reads the same `SKILL.md` files directly via a single repo-root manifest, `.codex-plugin/plugin.json`, that points at the existing `skills/` directory as a whole. No per-domain translation file exists or is needed. `.codex/INSTALL.md` documents both install paths (Codex's plugin marketplace, or a manual clone-and-symlink fallback), and `npx apple-agent-kit` now detects a Codex-only environment and prints the right instructions instead of erroring.
+- 2026-08-23 — Tier 2's 78 Knowledge Contracts and 17 Skills finished their first full pass through every Level 4 check, L4.1 through L4.5. The last of those, L4.5 — does the page a rule cites actually say what it's quoted as saying — had been explicitly left open by two earlier reviews because answering it means fetching live Apple documentation, not just reading the repository. Fetching it found what reading alone never could: fourteen fabricated-but-plausible quotes attached to otherwise-correct rules, a pair of stale rule-number citations, and one rule whose entire premise — that PassKit ships no SwiftUI equivalent for adding a pass to Wallet — had gone false the moment Apple shipped one, silently invalidating a coupling an earlier review had verified under the premise that held when it was written.
+- 2026-08-09 — The two-domain experiment was tested the way it was meant to be tested, and it passed with one gap. The idea under test: settle in writing, before any rule is authored, every boundary a new domain shares with the existing ones. Nine such boundaries were settled for the photo and location domains, and until now the only evidence they worked came from the person writing to them — not from someone using the result. So a realistic feature was put through the kit end to end: pick photos from the library, show where each one was taken, and react when the user comes back to that place later with the app closed. Four of the settled boundaries were exercised and all four held, including the one an agent is most likely to get wrong. The gap is elsewhere, and it is the interesting part: the photo library hands back a location — the place a photo was taken travels with the photo, and reading it needs no location permission at all — but neither domain said so, so a feature asking that question either stopped with nothing or asked the user for a permission it would never use. The reason nobody wrote it down is that the boundaries were settled by walking each new domain against the domains that already existed, which cannot see the seam between two domains built at the same time. That is now a written rule, along with the review question that would have caught it.
 Only the 3 most recent entries live here — see [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
 ## Contributing

package/bin/install.js

@@ -14,18 +14,37 @@ const commands = [
   ['claude', ['plugin', 'install', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`]],
 ];
 
-function checkClaudeInstalled() {
-  const result = spawnSync('claude', ['--version'], { stdio: 'ignore' });
-  if (result.error || result.status !== 0) {
-    console.error(
-      'Error: the `claude` CLI was not found on PATH. Install Claude Code first: https://code.claude.com/docs/en/quickstart'
-    );
-    process.exit(1);
-  }
+function commandExists(cmd) {
+  const result = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+  return !result.error && result.status === 0;
+}
+
+function printCodexInstructions() {
+  console.log('The `claude` CLI was not found on PATH, but `codex` was.');
+  console.log('Apple Agent Kit installs into Codex from inside a Codex session, not from this script.');
+  console.log('');
+  console.log('Run inside Codex:');
+  console.log(`  /plugin marketplace add ${REPO}`);
+  console.log('');
+  console.log('Then install the `apple-agent-kit` plugin from that marketplace and restart Codex.');
+  console.log(`For a manual install instead, see: https://github.com/${REPO}/blob/main/.codex/INSTALL.md`);
+}
+
+function printNeitherFoundError() {
+  console.error('Error: neither the `claude` nor the `codex` CLI was found on PATH.');
+  console.error('Install Claude Code: https://code.claude.com/docs/en/quickstart');
+  console.error('...or install Codex CLI, then re-run this command.');
 }
 
 function run() {
-  checkClaudeInstalled();
+  if (!commandExists('claude')) {
+    if (commandExists('codex')) {
+      printCodexInstructions();
+      process.exit(0);
+    }
+    printNeitherFoundError();
+    process.exit(1);
+  }
 
   for (const [cmd, args] of commands) {
     const printable = [cmd, ...args].join(' ');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-agent-kit",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "Installs the Apple Agent Kit Claude Code plugin via the claude CLI.",
   "bin": {
     "apple-agent-kit": "bin/install.js"