@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/hig-patterns/SKILL.md

@@ -1,99 +1,83 @@
 ---
 name: hig-patterns
-description: "Apple Human Interface Guidelines interaction and UX patterns. Use when an interaction or UX pattern on an Apple platform needs designing or reviewing."
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG interaction patterns mapped to SwiftUI: modality, loading, empty and error states, feedback, undo, search, data entry, settings, sharing, accounts. Use when designing a UX flow on an Apple platform."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Apple HIG: Interaction Patterns
+# HIG Patterns
 
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+A pattern is a recurring answer to a recurring flow question: how do people get
+started, how do they wait, how do they leave a task, how do they recover from a
+mistake. Apple's own apps answer these consistently, and people carry those
+expectations into yours. This skill lists the questions, the expected answer,
+and how to express it in SwiftUI.
 
-## Key Principles
+## Flow questions to settle first
 
-1. **Minimize modality.** Use modality only when it is critical to get attention, a task must be completed or abandoned, or saving changes is essential. Prefer non-modal alternatives.
+Before drawing screens, answer these for the flow under review:
 
-2. **Provide clear feedback.** Every action should produce visible, audible, or haptic response. Activity indicators for indeterminate waits, progress bars for determinate, haptics for physical confirmation.
+- Where does it start, and what does the person already know at that point?
+- Which step can they abandon, and what happens to their input if they do?
+- What do they see while the app is working?
+- What do they see when there is nothing to show, or when something fails?
+- How do they undo the last thing they did?
 
-3. **Support undo over confirmation dialogs.** Destructive actions should be reversible when possible. Undo is almost always better than "Are you sure?"
+Each maps to a pattern in `references/patterns.md`.
 
-4. **Launch quickly.** Display a launch screen that transitions seamlessly into the first screen. No splash screens with logos. Restore previous state.
+## Details on demand
 
-5. **Defer sign-in.** Let users explore before requiring account creation. Support Sign in with Apple and passkeys.
+Load `references/patterns.md` for launch, loading, empty and error states, feedback, undo, search, data entry, settings, sharing, accounts and notifications.
 
-6. **Keep onboarding brief.** Three screens max. Let users skip. Teach through progressive disclosure and contextual hints.
+## Choosing how to present a task
 
-7. **Use progressive disclosure.** Show essentials first, let users drill into details. Don't overwhelm with every option on one screen.
+| Situation | Treatment | SwiftUI |
+|-----------|-----------|---------|
+| Moving deeper into a hierarchy | Push | `NavigationLink(value:)` + `.navigationDestination` |
+| Self-contained task with its own done or cancel | Sheet | `.sheet(item:)` with `.presentationDetents` |
+| Task that needs the whole screen and focus | Full screen | `.fullScreenCover` |
+| Must acknowledge or decide before continuing | Alert | `.alert(_:isPresented:actions:message:)` |
+| Choosing among actions for the current item | Confirmation dialog | `.confirmationDialog` |
+| Quick, dismissible supplemental info | Popover or inline | `.popover`, inline disclosure |
 
-8. **Respect user attention.** Consolidate notifications, minimize interruptions, give users control over alerts. Never use notifications for marketing.
+Rules of thumb:
 
-## Topics
+- A sheet should have a clear way out: Cancel on the leading side, the
+  confirming action on the trailing side. Protect unsaved input with
+  `.interactiveDismissDisabled(hasChanges)` and a discard confirmation.
+- Avoid stacking modals. If a sheet opens another sheet, reconsider the flow.
+- Alerts are interruptions; use them for consequences, not for success.
 
-| Topic | Key content |
-|---|---|
-| Charting Data | Data visualization patterns, accessible charts, interactive elements |
-| Collaboration & Sharing | Share sheets, activity views, collaborative editing, SharePlay |
-| Drag and Drop | Drag sources, drop targets, spring loading, multi-item drag, visual feedback |
-| Entering Data | Text fields, pickers, steppers, input validation, keyboard types, autofill |
-| Feedback | Alerts, action sheets, haptic patterns, sound feedback, visual indicators |
-| File Management | Document browser, file providers, iCloud integration, document lifecycle |
-| Going Full Screen | Full-screen transitions, immersive content, exiting full screen |
-| Launching | Launch screens, state restoration, cold vs warm launch |
-| Live Viewing Apps | Live content display, real-time updates, Live Activities, Dynamic Island |
-| Loading | Activity indicators, progress views, skeleton screens, lazy loading, placeholders |
-| Managing Accounts | Sign in with Apple, passkeys, account creation, credential autofill, account deletion |
-| Managing Notifications | Permission requests, grouping, actionable notifications, provisional delivery |
-| Modality | Sheets, alerts, popovers, full-screen modals, when to use each |
-| Multitasking | iPad Split View, Slide Over, Stage Manager, responsive layout, size class transitions |
-| Offering Help | Contextual tips, onboarding hints, help menus, support links |
-| Onboarding | Welcome screens, feature highlights, progressive onboarding, skip options |
-| Playing Audio | Audio sessions, background audio, Now Playing, audio routing, interruptions |
-| Playing Haptics | Core Haptics, UIFeedbackGenerator, haptic patterns, custom haptics |
-| Playing Video | Video player controls, picture-in-picture, AirPlay, full-screen video |
-| Printing | Print dialogs, page setup, AirPrint integration |
-| Ratings & Reviews | SKStoreReviewController, timing, frequency limits, in-app feedback |
-| Searching | Search bars, suggestions, scoped search, results display, recents |
-| Settings | In-app vs Settings app, preference organization, toggles, defaults |
-| Undo and Redo | Shake to undo, undo/redo stack, multi-level undo |
-| Workouts | Workout sessions, live metrics, Always On display, summaries, HealthKit |
+## Review output
 
-## Pattern Selection Guide
+Name the flow step, the expected pattern, what the build does instead, and the
+change:
 
-| User Goal | Recommended Pattern | Avoid |
-|---|---|---|
-| First app experience | Brief onboarding (max 3 screens) + progressive disclosure | Long tutorials, mandatory sign-up |
-| Waiting for content | Skeleton screens or progress indicators | Blocking spinners with no context |
-| Confirming destructive action | Undo support | Excessive "Are you sure?" dialogs |
-| Collecting user input | Inline validation, smart defaults, autofill | Modal forms for simple inputs |
-| Requesting permissions | Contextual, just-in-time with explanation | Requesting all permissions at launch |
-| Providing feedback | Haptics + visual indicator | Silent actions with no confirmation |
-| Organizing preferences | In-app settings for frequent items | Burying all settings in system Settings app |
+```
+[Modality] Editing a product opens a full screen cover with no Cancel.
+Expected: sheet with Cancel and Save; discard confirmation when edited.
+```
 
-## Output Format
+## Related skills
 
-1. **Recommended pattern with rationale**, citing the relevant HIG topic.
-2. **Step-by-step implementation** covering each screen or state.
-3. **Platform variations** for targeted platforms.
-4. **Common pitfalls** that violate HIG for this pattern.
+- `hig-components-content`, `hig-components-system` for the parts of each pattern.
+- `swiftui-navigation` for push, sheet and deep link implementation.
+- `tipkit` for in-context onboarding.
 
-## Questions to Ask
+## References
 
-1. Where in the app does this pattern appear? What comes before and after?
-2. Which platforms?
-3. Designing from scratch or improving an existing flow?
-4. Does this involve sensitive actions? (Destructive operations, payments, permissions)
-
-## Related Skills
-
-- **hig-foundations** -- Accessibility, color, typography, and privacy principles underlying every pattern
-- **hig-platforms** -- Platform-specific pattern implementations
-- **hig-components-layout** -- Structural components (tab bars, sidebars, split views) for navigation patterns
-- **hig-components-content** -- Content display within patterns (charts, collections, search results)
-
----
-
-*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+- https://developer.apple.com/design/human-interface-guidelines/patterns
+- https://developer.apple.com/design/human-interface-guidelines/onboarding
+- https://developer.apple.com/design/human-interface-guidelines/launching
+- https://developer.apple.com/design/human-interface-guidelines/loading
+- https://developer.apple.com/design/human-interface-guidelines/modality
+- https://developer.apple.com/design/human-interface-guidelines/feedback
+- https://developer.apple.com/design/human-interface-guidelines/undo-and-redo
+- https://developer.apple.com/design/human-interface-guidelines/searching
+- https://developer.apple.com/design/human-interface-guidelines/entering-data
+- https://developer.apple.com/design/human-interface-guidelines/settings
+- https://developer.apple.com/design/human-interface-guidelines/drag-and-drop
+- https://developer.apple.com/design/human-interface-guidelines/managing-accounts
+- https://developer.apple.com/design/human-interface-guidelines/managing-notifications

package/pipeline/skills/shared/external/hig-patterns/references/patterns.md

@@ -0,0 +1,92 @@
+# Interaction patterns in detail
+
+Companion to `../SKILL.md` for the `hig-patterns` skill.
+
+## Starting: launch and onboarding
+
+- Launch straight into useful content. The launch screen should look like the
+  first frame of the app, not a splash advert.
+- Restore where the person left off (`@SceneStorage` for per-window state).
+- Keep onboarding optional and short. Teach in context instead, for example a
+  TipKit tip the first time someone opens the filters on a product list.
+- Ask for permissions at the moment they are needed, with a sentence of
+  context before the system prompt. Never ask for everything at launch.
+- Let people try the app before creating an account whenever possible.
+
+## Waiting: loading and progress
+
+- Show content as soon as any part is ready; load the rest progressively.
+- Use `ProgressView(value:total:)` when progress is measurable and an
+  indeterminate `ProgressView()` only for short, unknown waits.
+- For content shaped placeholders use `.redacted(reason: .placeholder)` on a
+  sample layout, which keeps the page from jumping when data arrives.
+- Keep the interface usable during long work; allow cancellation.
+- Pull to refresh with `.refreshable` on lists and scroll views.
+
+## Nothing to show, or something went wrong
+
+- Empty states explain what would appear and offer the next step:
+  `ContentUnavailableView("No notes yet", systemImage: "note.text", description: ...)`
+  with a button to create one.
+- For search with no results use `ContentUnavailableView.search(text:)`.
+- Errors say what happened in plain language and what to do. Offer retry for
+  transient failures; keep entered data intact.
+
+## Feedback and confirmation
+
+- Confirm success quietly and in place: a checkmark symbol effect, an updated
+  row, a brief haptic (`.sensoryFeedback(.success, trigger:)`).
+- Reserve alerts for failures that block progress.
+- Make destructive actions recoverable (undo, trash) rather than piling on
+  confirmation dialogs. Where there is no undo, confirm with a destructive-role
+  button (`Button("Delete Order", role: .destructive)`).
+
+## Undo
+
+- Register reversible edits with `@Environment(\.undoManager)`; shake to undo on
+  iPhone and Command-Z on iPad and Mac come with it.
+- Swipe-to-delete in a list should either be undoable or confirmed.
+
+## Search
+
+- Add `.searchable(text:)` to the navigation container so the field sits where
+  the platform expects it. Offer `.searchSuggestions` and `.searchScopes` for
+  large catalogs.
+- On iOS 26 a dedicated search tab (`Tab(role: .search)`) places search at the
+  bottom within reach.
+- Search as the person types when results are local; debounce remote queries.
+
+## Entering data
+
+- Ask only for what is needed; prefill what the app knows.
+- Pick the right keyboard and content type (`.keyboardType(.emailAddress)`,
+  `.textContentType(.emailAddress)`) so AutoFill works.
+- Validate inline next to the field, after the person leaves it, not on every
+  keystroke.
+- Move focus with `@FocusState` and `.submitLabel(.next)`.
+
+## Settings
+
+- Put settings people change often inside the app; put rarely changed ones in a
+  settings screen. On macOS use a `Settings` scene.
+- Keep defaults good enough that most people never visit settings.
+
+## Sharing, drag and drop, files
+
+- Use `ShareLink` with a `Transferable` model; the same conformance powers
+  `.draggable` and `.dropDestination`.
+- For document-based apps, `DocumentGroup` provides the browser, open, save and
+  rename behavior people expect.
+
+## Accounts
+
+- Offer Sign in with Apple wherever other third-party sign-in exists.
+- Support passkeys and AutoFill for passwords.
+- Provide in-app account deletion if the app lets people create an account.
+
+## Notifications
+
+- Notify about things people care about and that are time-sensitive, such as an
+  order that has shipped. Group by thread and set an interruption level that
+  matches urgency.
+- Deep link into the exact content the notification describes.

package/pipeline/skills/shared/external/hig-platforms/SKILL.md

@@ -1,81 +1,151 @@
 ---
 name: hig-platforms
-description: "Apple Human Interface Guidelines for platform-specific design. Use when a design has to fit a specific Apple platform's conventions."
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG per platform: iPhone, iPad, Mac, Watch, TV and Vision Pro conventions, and adapting one SwiftUI codebase across them. Use when a design has to fit a specific Apple platform."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Apple HIG: Platform Design
-
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
-
-## Key Principles
-
-1. **Each platform has a distinct identity.** Do not port designs between platforms. Respect each platform's conventions, interaction models, and user expectations.
-
-2. **iOS: touch-first.** Direct manipulation on a handheld screen. Optimize for one-handed use. Navigation uses tab bars and push/pop stacks.
-
-3. **iPadOS: expanded canvas.** Support Split View, Slide Over, and Stage Manager. Use sidebars and multi-column layouts. Support pointer and keyboard alongside touch.
-
-4. **macOS: pointer and keyboard.** Dense information display is acceptable. Use menu bars, toolbars, and keyboard shortcuts extensively. Windows are resizable with precise control.
-
-5. **tvOS: remote and focus.** Viewed from a distance. Design for the Siri Remote with focus-based navigation. Large text, simple layouts, linear navigation.
-
-6. **visionOS: spatial interaction.** 3D environment using windows, volumes, and spaces. Eye tracking for targeting, indirect gestures for interaction. Respect ergonomic comfort zones.
-
-7. **watchOS: glanceable and brief.** Information consumable at a glance. Brief interactions. Digital Crown, haptics, and complications for timely content.
-
-8. **Games: own paradigm.** Free to define in-game interaction models, but still respect platform conventions for system interactions (notifications, accessibility, controllers).
-
-## Topics
-
-| Topic | Key content |
-|---|---|
-| iOS | Touch, tab bars, navigation stacks, gestures, screen sizes, safe areas |
-| iPadOS | Multitasking, sidebars, pointer, keyboard, Apple Pencil, Stage Manager |
-| macOS | Menu bars, toolbars, window management, keyboard shortcuts, dense layouts, Dock |
-| tvOS | Focus engine, Siri Remote, lean-back experience, content-forward, parallax |
-| visionOS | Spatial computing, windows/volumes/spaces, eye tracking, hand gestures, depth |
-| watchOS | Glanceable UI, Digital Crown, complications, notifications, haptics |
-| Games | Controllers, immersive experiences, platform-specific conventions, accessibility |
-
-## Decision Framework
-
-1. **Identify the primary use context.** On the go (iOS/watchOS), at a desk (macOS), on the couch (tvOS), spatial environment (visionOS)?
-
-2. **Match input to interaction.** Touch for direct manipulation, pointer for precision, gaze+gesture for spatial, Digital Crown for quick scrolling, remote for focus navigation.
-
-3. **Adapt, don't replicate.** A macOS sidebar becomes a tab bar on iPhone. A visionOS volume has no equivalent on watchOS. Translate intent, not implementation.
-
-4. **Leverage platform strengths.** Live Activities on iOS, Desktop Widgets on macOS, complications on watchOS, immersive spaces on visionOS.
-
-5. **Maintain brand consistency** while respecting each platform's visual language and interaction patterns.
-
-## Output Format
-
-1. **Platform-specific recommendations** citing relevant HIG sections.
-2. **Platform differences table** comparing navigation, input, layout, and conventions.
-3. **Implementation notes** per platform including recommended APIs and adaptation strategies.
-
-## Questions to Ask
-
-1. Which platforms are you targeting?
-2. New app or adapting an existing one? If existing, which platform is the base?
-3. SwiftUI or UIKit/AppKit?
-4. Need to support older OS versions?
-5. Primary use context? (On the go, desk, couch, spatial, glanceable?)
-
-## Related Skills
-
-- **hig-foundations** -- Shared principles (color, typography, accessibility, layout) across platforms
-- **hig-patterns** -- Interaction patterns that manifest differently per platform
-- **hig-components-layout** -- Navigation structures (tab bars, sidebars, split views) that vary by platform
-- **hig-components-content** -- Content display that adapts across platforms
-
----
-
-*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+# HIG Platforms
+
+Every Apple platform has a different distance between person and screen, a
+different primary input, and a different idea of what an app session looks
+like. A screen that is right on iPhone is rarely right, unchanged, anywhere
+else. This skill gives the per-platform defaults, then the shared SwiftUI tools
+that let one codebase adapt instead of fork.
+
+## Start with three questions
+
+1. **How is it held or viewed?** In the hand, on a desk, on the wrist, across a
+   room, or floating in space. This sets text size, density and session length.
+2. **What is the primary input?** Touch, pointer and keyboard, Digital Crown,
+   a focus-driven remote, or eyes and hands.
+3. **How long is a visit?** Seconds on the wrist, minutes on the phone, hours on
+   the Mac.
+
+The answers usually decide navigation structure before any visual question.
+
+## Platform profiles
+
+### iPhone
+
+- One primary task per screen, reachable with a thumb. Primary actions low,
+  destructive ones behind confirmation.
+- Top-level navigation in a `TabView`; hierarchy inside each tab with
+  `NavigationStack`.
+- Portrait first, but layouts must not break in landscape or at accessibility
+  text sizes.
+- On iOS 26, standard tab bars and toolbars render in Liquid Glass and can
+  minimize on scroll (`.tabBarMinimizeBehavior(.onScrollDown)`); a search tab
+  can use `Tab(role: .search)`.
+
+### iPad
+
+- Treat it as a large, multitasking canvas, not a big phone. Support every
+  orientation and resizable windows (Stage Manager, and the free-form windowing
+  introduced in iPadOS 26).
+- Use `NavigationSplitView` for list-detail content such as orders and their
+  line items. Use `.tabViewStyle(.sidebarAdaptable)` so tabs can become a
+  sidebar.
+- Support pointer, hardware keyboard shortcuts (`.keyboardShortcut`) and Apple
+  Pencil where drawing or markup fits.
+- Support multiple scenes when documents or records can be open side by side.
+- iPadOS 26 adds a menu bar; populate it through `.commands` as on the Mac.
+
+### Mac
+
+- Windows are resizable, long-lived and often several at once. Use
+  `WindowGroup`, `Window`, `Settings` and `MenuBarExtra` scenes appropriately.
+- Every command belongs in the menu bar with a shortcut; toolbars hold the
+  frequent subset. Context menus mirror menu commands.
+- Higher density is expected: smaller controls, hover states, tooltips
+  (`.help`), multi-selection, drag and drop.
+- Sidebars, inspectors (`.inspector`) and tables (`Table`) are native idioms.
+- Mac Catalyst or "Designed for iPad" apps should still be checked for menu
+  bar completeness and pointer behavior.
+
+### Apple Watch
+
+- Glanceable: a visit lasts a few seconds. Show the one thing that matters now,
+  such as the status of the latest order.
+- Vertical `NavigationStack` or vertically paged `TabView`
+  (`.tabViewStyle(.verticalPage)`); avoid deep hierarchies.
+- Digital Crown scrolls and adjusts values (`.digitalCrownRotation`).
+- Complications and Smart Stack widgets through WidgetKit are often more used
+  than the app itself.
+- Large, full-width buttons; edge-to-edge content that follows the display's
+  rounded corners.
+
+### Apple TV
+
+- Viewed from across a room, driven by a focus engine and the Siri Remote.
+- Everything interactive must be focusable; use `.focusable()`, `@FocusState`
+  and `.focusSection()` to shape movement between groups.
+- Large type, generous spacing, content-forward layouts with lockups and
+  shelves. Keep text entry to a minimum.
+- Keep overscan-safe margins; the system containers already do.
+
+### Apple Vision Pro
+
+- Apps run in windows, volumes and optionally immersive spaces. Start in a
+  window; offer immersion only when it adds value.
+- Glass window backgrounds are the default; do not replace them with opaque
+  fills. Keep content in the center of the field of view.
+- Input is look and pinch. Give targets at least about 60 points of spacing and
+  let the system hover effect show focus (`.hoverEffect()` on custom views).
+- Use ornaments (`.ornament`) for toolbars and tab bars outside the window.
+- Depth is a tool for hierarchy, not decoration; keep text on flat planes.
+
+## One codebase, adapted
+
+| Need | SwiftUI tool |
+|------|--------------|
+| List and detail on large screens, stack on small | `NavigationSplitView` (collapses automatically) |
+| Tabs that become a sidebar | `.tabViewStyle(.sidebarAdaptable)` |
+| Layout switches on width | `@Environment(\.horizontalSizeClass)`, `ViewThatFits` |
+| Platform-only modifiers | `#if os(macOS)` / `#if os(visionOS)` kept at the edge of a view |
+| Commands shared by menu, shortcut and toolbar | `.commands`, `CommandMenu`, `.keyboardShortcut` |
+| Several windows of the same content | `WindowGroup(for: Order.ID.self)` plus `openWindow` |
+| Pointer affordances | `.hoverEffect`, `.onHover`, `.pointerStyle` (iPadOS/macOS 15+) |
+
+Keep platform conditionals small and local. A view that is half `#if` blocks
+is usually two views that should share a model instead.
+
+## Decision guide: what to drop or add
+
+- **Porting phone to watch:** drop browsing and editing; keep status, one or two
+  quick actions, and a complication.
+- **Porting phone to iPad:** add a sidebar, keyboard shortcuts, multiple
+  windows, drag and drop between apps.
+- **Porting iPad to Mac:** add a full menu bar, settings window, hover states
+  and higher density; remove anything that assumes touch only.
+- **Porting to TV:** strip dense forms; favor browsing and playback.
+- **Porting to visionOS:** keep the iPad layout as a starting window, then
+  replace custom opaque chrome with system glass and ornaments.
+
+## Review checklist
+
+- Navigation container matches the platform (tabs, split view, windows).
+- Primary input works end to end without the others (keyboard-only on Mac,
+  focus-only on TV, look-and-pinch on visionOS).
+- Targets meet the platform minimum size.
+- No device-model checks; adaptation keys off size class, scene and platform.
+- Text remains legible at the platform's viewing distance and user text size.
+
+## Related skills
+
+- `hig-foundations` for the base layer shared by all platforms.
+- `hig-inputs` for input-specific behavior.
+- `hig-components-layout` for split views, sidebars and tab bars in detail.
+- `swiftui-navigation` for navigation implementation.
+
+## References
+
+- https://developer.apple.com/design/human-interface-guidelines/platforms
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-ios
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-ipados
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-macos
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-tvos
+- https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos