{"id":"9aceec6e-90dd-4605-b254-4054b75dd438","shortId":"TkjYpe","kind":"skill","title":"swiftui-app-architecture-workflow","tagline":"Guide SwiftUI app-structure decisions for Apple apps across `App`, scenes, commands, focus, environment, preferences, window and document coordination, and reusable view composition. Use when the user wants help deciding where ownership belongs in a SwiftUI app, which data-flow m","description":"# SwiftUI App Architecture Workflow\n\n## Purpose\n\nProvide a docs-first workflow for SwiftUI app-structure decisions in Apple apps. This skill owns ownership-boundary guidance, transport-choice guidance, focused-context guidance, and anti-pattern correction for SwiftUI app composition across scenes, commands, focus, environment, preferences, and reusable view structure.\n\nIt is not the Apple-docs router, not the accessibility workflow, and not the Xcode execution workflow.\n\n## When To Use\n\n- Use this skill when the user wants help structuring a SwiftUI app across `App`, `Scene`, `WindowGroup`, `Window`, `Settings`, or `DocumentGroup`.\n- Use this skill when the user wants help deciding where app-level, scene-level, and view-level responsibilities belong.\n- Use this skill when the user wants help choosing between explicit dependency injection, environment values, focused values, scene-focused values, preference keys, bindings, or local state.\n- Use this skill when the user wants help with `FocusState`, `focusable`, focus scopes, focus sections, default focus, focused objects, or other focused-context design that changes ownership or data-flow choices.\n- Use this skill when the user wants help with command ownership, command menus, command groups, focused command handling, or desktop-oriented SwiftUI command surfaces.\n- Use this skill when the user wants help cleaning up giant root views, wrapper-heavy architecture, environment abuse, hidden control flow in modifiers, or state scattering in SwiftUI code.\n- Use this skill when the user wants SwiftUI composition guidance that stays grounded in current Apple scene and lifecycle behavior instead of framework-agnostic UI theory.\n- Recommend `explore-apple-swift-docs` when the user primarily needs Apple or Swift documentation lookup rather than architecture guidance.\n- Recommend `xcode-build-run-workflow` when the work becomes build, run, preview, diagnostics, file-membership, or guarded mutation work in an existing Xcode-managed project.\n- Recommend `xcode-testing-workflow` when the work becomes Swift Testing, XCTest, XCUITest, `.xctestplan`, or test diagnosis.\n- Recommend `apple-ui-accessibility-workflow` when the work is primarily about accessibility-specific implementation or review instead of absorbing that surface here.\n\n## When Not To Use\n\n- Do not use this skill as the primary path for raw Apple-docs search or source selection.\n- Do not use this skill as the primary path for SwiftUI styling, animation, or general component-library advice when the real issue is not app structure.\n- Do not use this skill as the primary path for execution-heavy validation of a proposed scene or command structure.\n- Do not use this skill as a generic dumping ground for every SwiftUI question just because a `View` is involved.\n\n## Single-Path Workflow\n\n1. Classify the request:\n   - app and scene structure\n   - commands\n   - focus and focused context\n   - environment and dependency flow\n   - upward data flow and preferences\n   - view-composition cleanup\n2. Apply the Apple docs gate before recommending structure:\n   - read the relevant SwiftUI documentation first\n   - state the documented behavior being relied on before giving architecture guidance\n   - if Apple docs and the current code disagree, stop and surface that conflict\n   - if no relevant Apple docs can be found, say that explicitly before proceeding\n3. Choose the ownership boundary:\n   - app-level\n   - scene-level\n   - focused-scene-level\n   - view-tree-level\n   - local view\n4. Choose the transport that fits the responsibility:\n   - explicit initializer injection\n   - `Binding`\n   - environment value\n   - `FocusState`\n   - focused value\n   - focused object\n   - focused scene value\n   - focused scene object\n   - preference key\n   - local state only\n5. Check the anti-patterns before finalizing guidance:\n   - app responsibilities stuffed into a leaf view\n   - scene responsibilities stuffed into a global environment object\n   - environment used as a dependency dump\n   - preference keys used as a general state bus\n   - giant root views with unrelated lifecycle, command, and rendering concerns mixed together\n   - wrapper-heavy layers added only to look architectural\n   - control flow hidden in modifiers that obscure who owns the action\n6. Return one recommendation path with:\n   - the ownership boundary\n   - the chosen transport\n   - the documented behavior being relied on\n   - the anti-pattern correction when relevant\n   - one handoff when the work is really docs lookup, execution, or accessibility work\n\n## Inputs\n\n- `request`: optional free-text task description used to classify the SwiftUI architecture question.\n- `scope`: optional explicit scope such as `app-scene-structure`, `commands`, `focus`, `environment`, `preferences`, or `composition`.\n- `platform_context`: optional platform emphasis such as `macos`, `ios`, `ipados`, or `mixed-apple`.\n- `repo_shape`: optional high-level repo context such as `xcode-app`, `document-app`, `multiwindow-app`, or `unknown`.\n- Defaults:\n  - docs-first guidance always applies\n  - desktop-oriented SwiftUI concerns stay in scope when they materially affect scene or command ownership\n  - explicit injection is preferred over broader implicit channels when both are viable and the narrower path is clearer\n\n## Outputs\n\n- `status`\n  - `success`: the request belongs to this workflow and a structure recommendation is ready\n  - `handoff`: the request belongs to another skill after SwiftUI-aware classification\n  - `blocked`: the request lacks enough context to recommend a boundary honestly\n- `path_type`\n  - `primary`: the recommendation comes from a directly supported architecture path\n  - `fallback`: the recommendation depends on limited request context because repo or platform shape is unclear\n- `output`\n  - resolved request class\n  - chosen ownership boundary\n  - chosen transport\n  - documented SwiftUI behavior relied on\n  - anti-pattern findings when relevant\n  - recommended skill when handing off\n  - one concise next step\n\n## Guards and Stop Conditions\n\n- Do not recommend environment values as a default substitute for explicit dependency flow.\n- Do not recommend preference keys for ordinary downward or lateral data flow.\n- Do not collapse commands, focus, and scene ownership into a single shared mutable object just because it is easy to wire.\n- Do not present a giant root view or extra wrapper layer as architectural improvement unless it clearly removes a real ownership problem.\n- Do not silently absorb accessibility-specific work, raw Apple-docs lookup, or Xcode execution work.\n- Stop with `blocked` when the request is too vague to determine whether the issue is app-level, scene-level, or local-view structure.\n\n## Fallbacks and Handoffs\n\n- Prefer explicit scope and platform context when the user provides them.\n- Fall back to request-text inference when repo shape and platform shape are unclear.\n- Recommend `explore-apple-swift-docs` when the real need is broader Apple or Swift docs lookup.\n- Recommend `xcode-build-run-workflow` when the next honest step is build, run, preview, diagnostics, file-membership follow-through, or guarded mutation.\n- Recommend `xcode-testing-workflow` when the next honest step is test execution or test diagnosis.\n- Recommend `apple-ui-accessibility-workflow` when the next honest step is accessibility-specific implementation or review.\n\n## Customization\n\nUse `references/customization-flow.md`.\n\n`scripts/customization_config.py` exists to preserve the repo-wide customization-file contract, but the first version of this skill defines no runtime-enforced knobs.\n\nKeep the first release focused on the decision model and the documented boundary. If future iterations add a real deterministic need for runtime knobs, document them explicitly before letting runtime behavior depend on them.\n\n## References\n\n### Workflow References\n\n- `references/app-and-scene-structure.md`\n- `references/navigation-splitview-sidebar-and-inspector.md`\n- `references/commands-and-focus.md`\n- `references/focus-and-focused-context.md`\n- `references/environment-and-preferences.md`\n- `references/architecture-decision-rules.md`\n- `references/anti-patterns-and-corrections.md`\n- `references/customization-flow.md`\n\n### Support References\n\n- Recommend `explore-apple-swift-docs` when the user needs direct Apple-docs lookup instead of SwiftUI architecture guidance.\n- Recommend `references/snippets/apple-xcode-project-core.md` when the user needs reusable repo policy rather than a one-off architecture recommendation.\n\n### Script Inventory\n\n- `scripts/customization_config.py`","tags":["swiftui","app","architecture","workflow","apple","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp"],"capabilities":["skill","source-gaelic-ghost","skill-swiftui-app-architecture-workflow","topic-agent-skills","topic-apple-development","topic-apple-docs","topic-apple-docs-mcp","topic-codex","topic-codex-app","topic-codex-cli","topic-codex-skills","topic-dash-docsets","topic-ios","topic-macos","topic-swift"],"categories":["apple-dev-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/gaelic-ghost/apple-dev-skills/swiftui-app-architecture-workflow","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add gaelic-ghost/apple-dev-skills","source_repo":"https://github.com/gaelic-ghost/apple-dev-skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (8,627 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:59.046Z","embedding":null,"createdAt":"2026-05-18T13:21:11.440Z","updatedAt":"2026-05-18T19:13:59.046Z","lastSeenAt":"2026-05-18T19:13:59.046Z","tsv":"'1':491 '2':517 '3':569 '4':590 '5':620 '6':690 'absorb':393,1004 'abus':269 'access':113,377,386,726,1006,1135,1144 'accessibility-specif':385,1005,1143 'across':15,93,136 'action':689 'ad':674 'add':1193 'advic':437 'affect':812 'agnost':305 'alway':799 'anim':431 'anoth':855 'anti':86,624,710,915 'anti-pattern':85,623,709,914 'app':3,9,14,16,43,50,63,68,91,135,137,155,444,495,575,629,750,785,788,791,1034 'app-level':154,574,1033 'app-scene-structur':749 'app-structur':8,62 'appl':13,67,108,296,311,319,375,413,520,544,559,772,1011,1076,1085,1133,1227,1236 'apple-doc':107,412,1010,1235 'apple-ui-accessibility-workflow':374,1132 'appli':518,800 'architectur':4,51,267,326,541,678,741,883,991,1242,1259 'awar':860 'back':1059 'becom':337,364 'behavior':300,535,704,911,1207 'belong':39,165,840,853 'bind':189,601 'block':862,1020 'boundari':74,573,698,871,906,1189 'broader':822,1084 'build':331,338,1093,1102 'bus':657 'chang':219 'channel':824 'check':621 'choic':78,225 'choos':174,570,591 'chosen':700,904,907 'class':903 'classif':861 'classifi':492,738 'clean':259 'cleanup':516 'clear':995 'clearer':834 'code':280,549 'collaps':960 'come':878 'command':18,95,235,237,239,242,249,465,499,664,753,815,961 'compon':435 'component-librari':434 'composit':29,92,289,515,758 'concern':667,805 'concis':926 'condit':932 'conflict':555 'context':82,216,503,760,780,867,892,1052 'contract':1163 'control':271,679 'coordin':25 'correct':88,712 'current':295,548 'custom':1149,1161 'customization-fil':1160 'data':46,223,509,956 'data-flow':45,222 'decid':36,152 'decis':11,65,1184 'default':208,794,940 'defin':1171 'depend':177,506,648,888,944,1208 'descript':735 'design':217 'desktop':246,802 'desktop-ori':245,801 'determin':1028 'determinist':1196 'diagnosi':372,1130 'diagnost':341,1105 'direct':881,1234 'disagre':550 'doc':57,109,313,414,521,545,560,722,796,1012,1078,1088,1229,1237 'docs-first':56,795 'document':24,322,530,534,703,787,909,1188,1201 'document-app':786 'documentgroup':143 'downward':953 'dump':475,649 'easi':976 'emphasi':763 'enforc':1175 'enough':866 'environ':20,97,179,268,504,602,642,644,755,936 'everi':478 'execut':119,457,724,1016,1127 'execution-heavi':456 'exist':351,1153 'explicit':176,566,598,745,817,943,1048,1203 'explor':310,1075,1226 'explore-apple-swift-doc':309,1074,1225 'extra':987 'fall':1058 'fallback':885,1044 'file':343,1107,1162 'file-membership':342,1106 'final':627 'find':917 'first':58,531,797,1166,1179 'fit':595 'flow':47,224,272,507,510,680,945,957 'focus':19,81,96,181,185,203,204,206,209,210,215,241,500,502,581,605,607,609,612,754,962,1181 'focused-context':80,214 'focused-scene-level':580 'focusst':202,604 'follow':1110 'follow-through':1109 'found':563 'framework':304 'framework-agnost':303 'free':732 'free-text':731 'futur':1191 'gate':522 'general':433,655 'generic':474 'giant':261,658,983 'give':540 'global':641 'ground':293,476 'group':240 'guard':346,929,1113 'guid':6 'guidanc':75,79,83,290,327,542,628,798,1243 'hand':923 'handl':243 'handoff':716,850,1046 'heavi':266,458,672 'help':35,131,151,173,200,233,258 'hidden':270,681 'high':777 'high-level':776 'honest':872,1099,1123,1140 'implement':388,1146 'implicit':823 'improv':992 'infer':1064 'initi':599 'inject':178,600,818 'input':728 'instead':301,391,1239 'inventori':1262 'involv':486 'io':767 'ipado':768 'issu':441,1031 'iter':1192 'keep':1177 'key':188,616,651,950 'knob':1176,1200 'lack':865 'later':955 'layer':673,989 'leaf':634 'let':1205 'level':156,159,163,576,579,583,587,778,1035,1038 'librari':436 'lifecycl':299,663 'limit':890 'local':191,588,617,1041 'local-view':1040 'look':677 'lookup':323,723,1013,1089,1238 'm':48 'maco':766 'manag':354 'materi':811 'membership':344,1108 'menus':238 'mix':668,771 'mixed-appl':770 'model':1185 'modifi':274,683 'multiwindow':790 'multiwindow-app':789 'mutabl':970 'mutat':347,1114 'narrow':831 'need':318,1082,1197,1233,1249 'next':927,1098,1122,1139 'object':211,608,614,643,971 'obscur':685 'one':692,715,925,1257 'one-off':1256 'option':730,744,761,775 'ordinari':952 'orient':247,803 'output':835,900 'own':71,687 'ownership':38,73,220,236,572,697,816,905,965,999 'ownership-boundari':72 'path':409,427,454,489,694,832,873,884 'pattern':87,625,711,916 'platform':759,762,896,1051,1069 'polici':1252 'prefer':21,98,187,512,615,650,756,820,949,1047 'present':981 'preserv':1155 'preview':340,1104 'primari':408,426,453,875 'primarili':317,383 'problem':1000 'proceed':568 'project':355 'propos':462 'provid':54,1056 'purpos':53 'question':480,742 'rather':324,1253 'raw':411,1009 'read':526 'readi':849 'real':440,998,1081,1195 'realli':721 'recommend':308,328,356,373,524,693,847,869,877,887,920,935,948,1073,1090,1115,1131,1224,1244,1260 'refer':1211,1213,1223 'references/anti-patterns-and-corrections.md':1220 'references/app-and-scene-structure.md':1214 'references/architecture-decision-rules.md':1219 'references/commands-and-focus.md':1216 'references/customization-flow.md':1151,1221 'references/environment-and-preferences.md':1218 'references/focus-and-focused-context.md':1217 'references/navigation-splitview-sidebar-and-inspector.md':1215 'references/snippets/apple-xcode-project-core.md':1245 'releas':1180 'relev':528,558,714,919 'reli':537,706,912 'remov':996 'render':666 'repo':773,779,894,1066,1158,1251 'repo-wid':1157 'request':494,729,839,852,864,891,902,1023,1062 'request-text':1061 'resolv':901 'respons':164,597,630,637 'return':691 'reusabl':27,100,1250 'review':390,1148 'root':262,659,984 'router':110 'run':332,339,1094,1103 'runtim':1174,1199,1206 'runtime-enforc':1173 'say':564 'scatter':277 'scene':17,94,138,158,184,297,463,497,578,582,610,613,636,751,813,964,1037 'scene-focus':183 'scene-level':157,577,1036 'scope':205,743,746,808,1049 'script':1261 'scripts/customization_config.py':1152,1263 'search':415 'section':207 'select':418 'set':141 'shape':774,897,1067,1070 'share':969 'silent':1003 'singl':488,968 'single-path':487 'skill':70,126,146,168,195,228,253,283,405,423,450,471,856,921,1170 'skill-swiftui-app-architecture-workflow' 'sourc':417 'source-gaelic-ghost' 'specif':387,1007,1145 'state':192,276,532,618,656 'status':836 'stay':292,806 'step':928,1100,1124,1141 'stop':551,931,1018 'structur':10,64,102,132,445,466,498,525,752,846,1043 'stuf':631,638 'style':430 'substitut':941 'success':837 'support':882,1222 'surfac':250,395,553 'swift':312,321,365,1077,1087,1228 'swiftui':2,7,42,49,61,90,134,248,279,288,429,479,529,740,804,859,910,1241 'swiftui-app-architecture-workflow':1 'swiftui-awar':858 'task':734 'test':359,366,371,1118,1126,1129 'text':733,1063 'theori':307 'togeth':669 'topic-agent-skills' 'topic-apple-development' 'topic-apple-docs' 'topic-apple-docs-mcp' 'topic-codex' 'topic-codex-app' 'topic-codex-cli' 'topic-codex-skills' 'topic-dash-docsets' 'topic-ios' 'topic-macos' 'topic-swift' 'transport':77,593,701,908 'transport-choic':76 'tree':586 'type':874 'ui':306,376,1134 'unclear':899,1072 'unknown':793 'unless':993 'unrel':662 'upward':508 'use':30,123,124,144,166,193,226,251,281,400,403,421,448,469,645,652,736,1150 'user':33,129,149,171,198,231,256,286,316,1055,1232,1248 'vagu':1026 'valid':459 'valu':180,182,186,603,606,611,937 'version':1167 'viabl':828 'view':28,101,162,263,484,514,585,589,635,660,985,1042 'view-composit':513 'view-level':161 'view-tree-level':584 'want':34,130,150,172,199,232,257,287 'whether':1029 'wide':1159 'window':22,140 'windowgroup':139 'wire':978 'work':336,348,363,381,719,727,1008,1017 'workflow':5,52,59,114,120,333,360,378,490,843,1095,1119,1136,1212 'wrapper':265,671,988 'wrapper-heavi':264,670 'xcode':118,330,353,358,784,1015,1092,1117 'xcode-app':783 'xcode-build-run-workflow':329,1091 'xcode-manag':352 'xcode-testing-workflow':357,1116 'xctest':367 'xctestplan':369 'xcuitest':368","prices":[{"id":"ab5d8ddc-f51e-4ea6-b318-546073a6048b","listingId":"9aceec6e-90dd-4605-b254-4054b75dd438","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"gaelic-ghost","category":"apple-dev-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:11.440Z"}],"sources":[{"listingId":"9aceec6e-90dd-4605-b254-4054b75dd438","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/swiftui-app-architecture-workflow","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/swiftui-app-architecture-workflow","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:11.440Z","lastSeenAt":"2026-05-18T19:13:59.046Z"}],"details":{"listingId":"9aceec6e-90dd-4605-b254-4054b75dd438","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"swiftui-app-architecture-workflow","github":{"repo":"gaelic-ghost/apple-dev-skills","stars":7,"topics":["agent-skills","apple-development","apple-docs","apple-docs-mcp","codex","codex-app","codex-cli","codex-skills","dash-docsets","ios","macos","swift","swift-package-manager","swift-toolchain","swiftly","swiftpm","xcode","xcode-mcp","xcodebuild","xcrun"],"license":"apache-2.0","html_url":"https://github.com/gaelic-ghost/apple-dev-skills","pushed_at":"2026-05-13T01:26:51Z","description":"Apple Dev Workflows for Codex | Now Available in Socket Marketplace","skill_md_sha":"713634e08f034fcc45c9dee710a2899ce0bf7f59","skill_md_path":"skills/swiftui-app-architecture-workflow/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/swiftui-app-architecture-workflow"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"swiftui-app-architecture-workflow","description":"Guide SwiftUI app-structure decisions for Apple apps across `App`, scenes, commands, focus, environment, preferences, window and document coordination, and reusable view composition. Use when the user wants help deciding where ownership belongs in a SwiftUI app, which data-flow mechanism fits a responsibility, or how to correct wrapper-heavy and state-scattering SwiftUI shapes without drifting into generic styling or execution work."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/swiftui-app-architecture-workflow"},"updatedAt":"2026-05-18T19:13:59.046Z"}}