Custom

Implement native iOS auth with ClerkKit primitives while keeping flow and layout very close to ClerkKitUI AuthView by default.

Source-Driven Requirements

Use installed package source from Xcode DerivedData:

• ~/Library/Developer/Xcode/DerivedData/.../SourcePackages/checkouts/clerk-ios

Source priority rules for custom flow:

• Primary source: installed ClerkKitUI source for auth UI behavior and gating parity.
• Secondary source: installed ClerkKit source for core auth/network/config behavior.
• Fallback only: example apps (local or GitHub) when behavior is unclear from library source.

For custom flows, treat ClerkKitUI AuthView as a strict parity target for:

• step progression/sequencing
• field visibility and hidden-state rules per step
• branching between factors/strategies
• screen structure and layout composition per step
• view hierarchy and section ordering per step

Required Patterns

1. Package products

• If clerk-ios is not installed, add it using the latest available release with an up-to-next-major package requirement.
• Do not pin an exact package version unless the developer explicitly requests version pinning.
• Add ClerkKit by default.
• Add ClerkKitUI only if the developer explicitly asks for mixed prebuilt/custom composition.

2. Quickstart prerequisite audit

• Find the iOS quickstart URL in the installed clerk-ios package README, append .md, then visit and read that markdown URL.
• Build a checklist from the visited markdown quickstart and verify the current project completed all required setup.
• If required setup is missing, add it before finishing custom auth implementation.
• Always add any missing Associated Domains entries and any other capabilities required by the quickstart.
• Explicitly apply quickstart step Add associated domain capability (https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability); ensure webcredentials:{YOUR_FRONTEND_API_URL} exists when missing.

3. Environment inspection + normalization

• Inspect installed ClerkKitUI source first to identify which Environment fields and semantics drive flow behavior.
• Build an agent-internal Environment field map from that source inspection.
• Make a direct HTTP call to /v1/environment only after the Environment field map is defined.
• Derive from the response using that ClerkKitUI-aligned field map (agent-internal only):
  • normalized ClerkKitUI-style capability matrix
  • required-field matrix
• Drive custom-flow implementation decisions from these matrices.
• Do not serialize or add these matrices as source artifacts in the app codebase.

4. Combined-entry default

• Keep a combined sign-in-or-sign-up entry by default.
• Do not add a local sign-in/sign-up mode switcher unless explicitly requested.

5. AuthView progression parity

• Follow ClerkKitUI AuthView progression logic for advancing/regressing steps.
• Show/hide inputs exactly according to the active step requirements instead of static form layouts.
• Keep factor/strategy branching aligned with how AuthView gates transitions.
• Keep screen layout and component structure very close to AuthView defaults unless the developer explicitly requests a different UX.
• Keep view hierarchy and section ordering close to AuthView on each step; do not redesign the information architecture unless explicitly requested.
• Break the custom flow into multiple step screens/states similar to AuthView; do not try to gather all signup/signin requirements in one view.
• If proposed custom layout materially deviates from AuthView, stop and ask for explicit developer approval before implementing.

6. Multi-file organization and separation of concerns

• Break custom auth flow into focused files/modules instead of one large screen file.
• Separate UI step views, flow/state orchestration, and Clerk/network integration responsibilities.
• Keep per-file responsibilities narrow and composable so new factors/steps can be added without rewriting a monolithic view.

7. Capability-matrix-driven implementation

• Drive custom flow behavior from normalized ClerkKitUI-style capability mapping.
• Do not rely on one-off raw environment checks.
• Apply matrix outcomes to runtime flow logic only; do not add matrix models/constants/files to the project.
• Ensure custom logic uses the same environment-field gates and interpretations that ClerkKitUI uses.

8. Required-field coverage

• Implement all required fields from required-field matrix.
• Do not ship flow with missing required fields.

9. Apple sign-in policy

• Implement Apple via native Clerk Apple path.
• If Apple capability is required for this app and missing, add it.
• Do not implement Apple through generic social-provider OAuth handling.

10. Source parity

• Follow installed ClerkKitUI and ClerkKit source patterns for sequencing, factor handling, and verification steps.
• When unsure about custom-flow implementation details, sequencing, gating, or Environment usage/semantics, stop guessing and reference installed ClerkKitUI implementation behavior.
• Resolve ambiguity by mirroring ClerkKitUI behavior unless the developer explicitly asks for a different approach.

Verification Checklist

1. Quickstart prerequisites are complete

• Quickstart link was sourced from installed clerk-ios package README, .md was appended, and the markdown page was visited/read.
• Required project setup from quickstart is present.
• Any missing quickstart-required Associated Domains/capabilities were added, not just reported.
• Quickstart Add associated domain capability step was applied, including webcredentials:{YOUR_FRONTEND_API_URL}.

2. No unrequested mode switcher

• No local toggle/segmented control/tabs for sign-in vs sign-up unless explicitly requested.

3. Environment call completed

• Installed ClerkKitUI Environment field usage was inspected before calling /v1/environment.
• Direct /v1/environment call succeeded after field-map inspection.

4. AuthView flow parity

• Step transitions follow AuthView progression rules.
• Inputs shown at each step match AuthView step-level visibility behavior.
• Step layouts and component grouping are materially close to AuthView; do not introduce major layout redesign unless explicitly requested.
• View hierarchy/section ordering remain close to AuthView across steps unless explicitly requested otherwise.
• Flow is split across multiple steps like AuthView; required data is not collected in one monolithic screen.
• When implementation ambiguity appears, final behavior matches installed ClerkKitUI rather than an inferred/custom interpretation.

5. Flow organization quality

• Custom flow code is split into multiple focused files/modules (not a single monolithic auth view file).
• UI, state/flow orchestration, and integration logic are separated with clear boundaries.

6. Matrices created and used

• Capability matrix and required-field matrix exist and drive the implementation.
• Matrix artifacts are not written into project source files.
• Environment fields used for gating/requirements match the set and semantics used by installed ClerkKitUI.

7. Required fields covered

• Required-field matrix has full coverage in custom UI.

8. Capability-map parity

• Feature availability and branching use normalized capability map.

9. Apple path correctness

• Apple flow uses native path, not generic provider OAuth path.

10. No unrequested prebuilt dependency

• ClerkKitUI is not added unless explicitly needed.