gaelic-ghost/socket/app-extension-architecture-workflow

App Extension Architecture Workflow

Purpose

Choose and structure an Apple app extension before implementation. Apple documents app extensions as separate bundles whose code runs in a separate process; the extension point and host define the lifecycle, APIs, and activation contract. This skill owns those reusable mechanics, not product-specific framework behavior.

It owns extension-point routing, target and process boundaries, activation, entitlements, app groups and shared containers, bounded data flow, privacy, testing, signing, and distribution. It does not absorb MailKit, File Provider, Finder Sync, Safari, Messages/iMessage, communication-notification, VoIP, Push to Talk, widget, intent, or other product-framework guidance.

When To Use

• Use this skill when a request needs an Apple app extension but the right extension point, host relationship, or target structure is unclear.
• Use this skill when planning a containing app and extension targets, process isolation, activation, app groups, shared containers, XPC, privacy boundaries, signing, or distribution.
• Use mailkit-workflow for macOS Mail content blocking, message actions, compose sessions, or message security.
• Use file-provider-and-finder-sync-workflow for remote storage synchronization or Finder badges, menus, and monitored-folder visibility.
• Use safari-extension-control-workflow for Safari-specific extension and SafariServices choices.
• Use Messaging Collaboration Skills for Messages/iMessage collaboration, communication-notification policy, VoIP, or Push to Talk workflows.
• Recommend explore-apple-swift-docs when the immediate need is current Apple documentation for a named extension point.
• Recommend xcode-build-run-workflow or xcode-testing-workflow when target execution or test mechanics are the next step.

Single-Path Workflow

1. Classify the extension point and host:

• name the system host, supported platform, activation trigger, user-visible configuration, and expected lifetime
• choose an existing Apple extension point and its documented template or contract; do not invent a generic extension target
• route product behavior to its dedicated workflow before designing shared mechanics

1. State the documented behavior relied on:

• app extensions are separate bundles that run in separate processes
• the host controls activation and the extension-point API contract
• use the extension point’s APIs and lifecycle rather than assuming the containing app is running or reachable
• stop and surface a conflict if current code assumes a lifecycle, privilege, or data access that Apple documentation does not support

1. Design targets and ownership:

• give the containing app, each extension target, and any shared framework or package one clear job
• in the canonical product workspace, place every extension target directly at Apps/<ExtensionTarget>/ as a peer of its containing app and test targets; never create a root Extensions/ tree
• require the containing app's XcodeGen target dependency to name and embed the extension explicitly; directory proximity or target naming is not host evidence
• keep extension entry points thin; put portable domain logic in deliberately shared source only when both targets need it
• do not use a shared target to smuggle UI, host-only state, or privileged access across process boundaries

1. Define the process and data-flow contract:

• state where each operation runs, how work is activated, what happens when the host interrupts or relaunches it, and what can be retried safely
• prefer the extension point’s documented request, completion, and cancellation APIs
• use XPC only where the extension-point contract or a documented app-extension API actually supports it
• make payload types small, typed, versioned when persisted, and free of secrets unless the secure storage and access policy is explicit

1. Minimize entitlements and shared state:

• grant each target only the capabilities it needs
• use an App Group only when the app and extension genuinely need a shared container or documented IPC support
• validate membership in every participating target; on macOS, test actual container access rather than trusting a returned URL alone
• do not treat an App Group as a general cross-process database, privilege escalation path, or substitute for an extension-point API

1. Plan privacy and failure behavior:

• inventory data read by the host, extension, and shared container separately
• retain the minimum data for the minimum time, avoid sensitive logs, and make user-facing effects explainable
• define cancellation, timeout, unavailable-host, disabled-extension, migration, and stale-shared-state behavior before shipping

1. Plan validation and distribution:

• validate target membership, Info.plist extension-point configuration, entitlements, signing, embedding, install/enable state, activation, and clean-device behavior
• test the extension independently where its framework permits; extract pure/shared logic into a testable target instead of trying to unit-test an unsupported extension process directly
• validate the same signing and distribution path intended for users; do not infer App Store, notarization, or enterprise behavior from a development build

1. Return one recommendation with the extension point, target map, lifecycle/data-flow boundary, entitlement/share plan, privacy plan, validation sequence, and the next focused handoff.
2. Hand settled target creation or existing-target adoption to

bootstrap-xcode-workspace --operation add-component|adopt; this workflow chooses the extension contract while the workspace workflow owns placement, XcodeGen registration, host embedding, and the permanent project graph.

Inputs

• request: optional extension feature request.
• platforms: optional Apple platforms and deployment targets.
• host: optional system host or containing-app context.
• data_needs: optional private, shared, remote, or user-selected data requirements.
• distribution: optional development, TestFlight, App Store, notarized, enterprise, or unknown path.
• Defaults:
• use a documented extension point and its host contract
• preserve process isolation and least privilege
• prefer no shared container until a concrete shared-data need exists
• keep product-specific behavior in its dedicated Apple or Messaging Collaboration workflow

Outputs

• status: success, handoff, or blocked.
• extension_plan:
• selected extension point and documented behavior relied on
• containing-app, extension-target, and shared-code ownership
• activation, process, lifecycle, cancellation, and restart behavior
• entitlement, App Group, container, and data-flow decisions
• privacy, signing, distribution, and validation plan
• explicit next workflow handoff

Guards and Stop Conditions

• Do not call an extension a thread or assume it shares the containing app’s memory, lifecycle, or UI state.
• Do not add a generic coordinator, manager, bridge, repository, or shared store merely to connect an app and extension. Name the documented transport and the concrete data it carries.
• Do not add an App Group, shared Keychain access group, network entitlement, or broad file access without naming the participating targets and the required data flow.
• Do not place Messages/iMessage collaboration, communication-notification product policy, VoIP, or Push to Talk behavior in this workflow.
• Do not claim an extension is enabled, activated, signed, distributable, or testable until the relevant host and build evidence exists.
• Do not create or recommend a root Extensions/ directory, a separate

extension project, or an inferred host relationship. Extensions are peer targets under Apps/ and the containing app embeds them explicitly.

• Stop with blocked when the requested behavior needs an undocumented extension point, host privilege, private system data, or cross-process access the platform does not expose.

Fallbacks and Handoffs

• Recommend macos-sandbox-file-access-workflow for user-selected files, security-scoped bookmarks, shared-container access lifetime, and file authorization across an extension process boundary.
• Recommend diagnose-apple-entitlements when an extension/helper capability differs between tracked source, profile authorization, final nested signature, and runtime behavior.
• Recommend mailkit-workflow for the macOS Mail extension point and its handler contracts.
• Recommend file-provider-and-finder-sync-workflow for remote-storage sync or Finder-only integrations.
• Recommend safari-extension-control-workflow for Safari-specific extension choices.
• Recommend app-intents-workflow for App Intents and system-intent execution.
• Recommend xcode-build-run-workflow for Xcode target creation, build settings, entitlements, signing, embedding, install, and run work.
• Recommend bootstrap-xcode-workspace for canonical extension target creation,

Apps/ placement, existing-repository adoption, and XcodeGen host embedding.

• Recommend xcode-testing-workflow for XCTest, XCUITest, test plans, and execution evidence.
• Recommend macos-distribution-workflow for macOS signing, notarization, Gatekeeper, and artifact inspection.
• Recommend explore-apple-swift-docs for a current Apple documentation pass before choosing an unfamiliar extension point.
• Recommend references/snippets/apple-xcode-project-core.md for reusable project-structure policy after the extension plan is settled.

References

Workflow References

• references/extension-points-targets-and-lifecycle.md
• references/entitlements-shared-containers-and-data-flow.md
• references/privacy-validation-signing-and-distribution.md

Authoritative Sources

• Adding support for app extensions to your app
• Building an app extension to support a host app
• Configuring app groups

Support References

• Recommend references/snippets/apple-xcode-project-core.md for reusable Xcode project guidance for containing-app and extension-target work.

Script Inventory