feat: Add iOS and Swift context files and guidelines for answering programming questions

.opencode/agents/fidelity.md

@@ -32,3 +32,5 @@ Behavior rules:
 - Do not wait for a dedicated sync command if the correct memory update is already obvious.
 - Do not over-promote uncertain information. Keep uncertain items in the daily log.
 - When drafting communication, preserve technical meaning and improve clarity in natural US English.
+- When answering Swift/iOS programming questions, use the project-local iOS skills and `ai/context/ios/`.
+- If the answer depends on current Apple APIs or Xcode/iOS behavior, verify with official Apple or Swift documentation before presenting it as current best practice.

.opencode/commands/fidelity-context.md

@@ -10,6 +10,9 @@ Use these files as the baseline context:
 @ai/AGENTS.md
 @ai/context/index.md
 @ai/context/project.md
+@ai/context/ios/index.md
+@ai/context/ios/current-practices.md
+@ai/context/ios/project-swift-guidance.md
 @ai/context/systems/index.md
 @ai/context/workstreams/index.md
 @ai/context/process/communication.md

.opencode/commands/swift-help.md

@@ -0,0 +1,36 @@
+---
+description: Answer Swift or iOS programming questions with Fidelity/XFlow context
+---
+
+Answer the user's Swift/iOS programming question using current iOS practices and this workspace's Fidelity context.
+
+Read:
+
+@ai/AGENTS.md
+@ai/context/ios/index.md
+@ai/context/ios/current-practices.md
+@ai/context/ios/project-swift-guidance.md
+@ai/context/index.md
+@ai/context/systems/index.md
+@ai/context/workstreams/index.md
+@ai/work-items/index.md
+@knowledge/agent-memory-rules.md
+
+User question:
+
+$ARGUMENTS
+
+Instructions:
+
+- Use the `ios-swift-answering` skill if available.
+- Use `swiftui-xflow-review` if the question touches SwiftUI, XFlow, UIKit bridge removal, modal presentation, lifecycle, or backend-driven UI.
+- Use `ios-testing-strategy` if the question touches tests or validation.
+- If current Apple API behavior matters, verify against official Apple or Swift documentation before making strong claims.
+- Contextualize the answer to Fidelity only when it materially changes the recommendation.
+- Separate current best practice from project-safe recommendation when they differ.
+
+Return:
+
+1. Recommendation
+2. Project-specific caveats
+3. Validation or follow-up checks

.opencode/plugins/fidelity-compaction.js

@@ -16,6 +16,9 @@ export const FidelityCompaction = async ({ directory }) => {
         "README.md",
         "ai/context/index.md",
         "ai/context/project.md",
+        "ai/context/ios/index.md",
+        "ai/context/ios/current-practices.md",
+        "ai/context/ios/project-swift-guidance.md",
         "ai/context/systems/index.md",
         "ai/context/workstreams/index.md",
         "ai/context/process/communication.md",

.opencode/skills/ios-swift-answering/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ios-swift-answering
+description: Answer Swift, SwiftUI, and iOS programming questions using current Apple guidance while adapting recommendations to Fidelity/XFlow project constraints.
+compatibility: opencode
+---
+
+## When To Use
+
+Use this skill for Swift, SwiftUI, iOS architecture, concurrency, testing, or debugging questions.
+
+## Workflow
+
+1. Identify whether the question is general Swift/iOS or Fidelity-specific.
+2. Read `ai/context/ios/current-practices.md` for currentness rules.
+3. Read `ai/context/ios/project-swift-guidance.md` when the answer may affect XFlow, Fid4, XFlowViewMaker, FTFrameworks, feature flags, or consumer validation.
+4. If the answer depends on current Apple APIs, Xcode versions, or migration guidance, verify with official Apple/Swift documentation before making strong claims.
+5. Separate:
+   - current best practice
+   - project-safe recommendation
+   - assumptions to confirm
+
+## Output Rules
+
+- Be direct and senior-engineer practical.
+- Avoid generic architecture advice when project constraints matter.
+- Do not assume deployment target, Xcode version, or framework migration status.
+- Mention tradeoffs and validation path when relevant.

.opencode/skills/ios-testing-strategy/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ios-testing-strategy
+description: Recommend iOS testing approaches for Swift, SwiftUI, XFlow, Fid4, and REST migration work while respecting existing XCTest/Swift Testing/project constraints.
+compatibility: opencode
+---
+
+## When To Use
+
+Use this skill for unit tests, UI tests, integration tests, regression coverage, XFlow flow validation, or REST/GraphQL migration testing questions.
+
+## Workflow
+
+1. Identify the behavior under test.
+2. Classify the test level:
+   - unit
+   - integration
+   - UI / consumer flow
+   - exploratory validation
+3. Check whether the behavior depends on backend configuration, auth state, entry point, feature flags, or Fid4 integration.
+4. Prefer the test framework already used by the project unless the user asks about migration.
+5. If suggesting Swift Testing, confirm Xcode/project support first and do not mix APIs inside the same test.
+
+## Project-Specific Guidance
+
+- XFlow behavior may require exploratory validation beyond unit tests.
+- AO/Discourse issues often need auth-state and entry-point coverage.
+- REST migration tests must distinguish REST path from GraphQL fallback.
+- Consumer-facing changes may require Fid4 validation even when SDK tests pass.
+
+## Output Rules
+
+- Recommend the smallest useful test strategy.
+- Include what cannot be proven by that test layer.
+- Mention manual/exploratory validation when code-level tests are insufficient.

.opencode/skills/swiftui-xflow-review/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: swiftui-xflow-review
+description: Review or reason about SwiftUI code in XFlow/Fidelity contexts, especially lifecycle, modal presentation, navigation, backend-driven UI, and UIKit bridge removal.
+compatibility: opencode
+---
+
+## When To Use
+
+Use this skill when a SwiftUI question touches XFlow, Fid4, XFlowViewMaker, modal presentation, dismissal sequencing, navigation, `UIHostingController`, or backend-driven UI behavior.
+
+## Review Heuristics
+
+- Check whether behavior is driven by backend configuration before blaming local SwiftUI code.
+- Identify data ownership and view lifecycle boundaries.
+- Treat dismissal sequencing as high risk when delegate callbacks, `onDisappear`, or upstream state changes are involved.
+- Treat UIKit bridge removal as rollout-sensitive, not just cleanup.
+- Separate SwiftUI best practice from Fidelity-safe migration strategy.
+
+## Fidelity-Specific Checks
+
+- Does the change preserve UIKit/SwiftUI parity?
+- Does it require a feature flag?
+- Does it need validation in Fid4 or only XFlowSDK?
+- Could XFlowViewMaker or FTFrameworks block consumer visibility?
+- Is the issue external behavior, existing behavior, or a regression?
+
+## Output Rules
+
+- Provide a clear recommendation.
+- Include risks and validation path.
+- Avoid recommending a pure SwiftUI approach without noting rollout and consumer validation impact.

AGENTS.md

@@ -16,6 +16,9 @@ The detailed operating rules live in:
 - `ai/AGENTS.md`
 - `ai/context/index.md`
 - `ai/context/project.md`
+- `ai/context/ios/index.md`
+- `ai/context/ios/current-practices.md`
+- `ai/context/ios/project-swift-guidance.md`
 - `ai/context/systems/index.md`
 - `ai/context/workstreams/index.md`
 - `ai/context/process/communication.md`
@@ -53,6 +56,8 @@ These are also loaded through `opencode.json`.
 - Prefer correcting canonical context over appending contradictory notes.
 - Keep changes concise and auditable.
 - When the topic is architectural or historical, prefer updating the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` instead of overloading `ai/context/project.md`.
+- When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `ai/context/ios/` and the local OpenCode iOS skills before answering.
+- If a Swift/iOS recommendation depends on current Apple APIs, Xcode behavior, or framework migration guidance, verify against official Apple or Swift documentation before making strong claims.
 
 ## Communication
 

README.md

@@ -53,6 +53,7 @@ Runtime context for AI support.
 
 - `AGENTS.md` -> behavior rules for AI agents
 - `context/` -> stable knowledge organized by systems, workstreams, process, people, and decisions
+- `context/ios/` -> Swift and iOS answer policy for current best practices and Fidelity-specific constraints
 - `work-items/` -> one file per active Jira-linked unit of work
 - `state/` -> current focus, active issues, and communication needs
 - `logs/` -> daily work record

ai/AGENTS.md

@@ -63,6 +63,7 @@ When drafting messages for a manager or stakeholder:
 - Treat workspace files as persistent memory, not just reference notes
 - Before answering prompts about current work, verify `ai/state/current.md` and the latest relevant log in `ai/logs/`
 - Before answering architecture, process, or historical questions, check the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/`
+- Before answering Swift, SwiftUI, iOS architecture, testing, or debugging questions, check `ai/context/ios/` and use the project-local iOS skills when available
 - If `ai/inbox/mattermost-latest.md` exists, check it before answering prompts about current status, standups, or supervisor communication
 - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands
 - If a Mattermost sync or other context-ingestion step fails, do not update `ai/logs/`, `ai/state/`, or stable context files based on that failure
@@ -78,6 +79,7 @@ When drafting messages for a manager or stakeholder:
 - Update existing memory when the new information is a correction, clarification, or refinement of something already stored
 - Prefer updating stable project context over appending generic operational summaries
 - Do not create daily log entries for tooling activity, sync status, or generic chat noise
+- For Swift/iOS best-practice answers, distinguish current Apple guidance from project-safe recommendations when Fidelity constraints may change the answer
 - Do not ask the user what should be promoted after a successful sync unless multiple conflicting interpretations are equally plausible
 - When the user shares relevant new information, update today's log if the information belongs to the daily record
 - When the user corrects or changes stable context, update the canonical file directly:

ai/context/index.md

@@ -21,6 +21,14 @@ Stable context about core product components and how they relate:
 - [systems/xflowviewmaker.md](./systems/xflowviewmaker.md)
 - [systems/ftframeworks.md](./systems/ftframeworks.md)
 
+### `ios/`
+
+Swift and iOS best-practice context for programming questions:
+
+- [ios/index.md](./ios/index.md)
+- [ios/current-practices.md](./ios/current-practices.md)
+- [ios/project-swift-guidance.md](./ios/project-swift-guidance.md)
+
 ### `workstreams/`
 
 Durable context about recurring streams of work and investigation:
@@ -56,5 +64,6 @@ Confirmed technical or product decisions with ongoing impact.
 
 - Load `project.md` and this index first.
 - Open `systems/` when the question is about architecture, ownership, or integration.
+- Open `ios/` when the question is about Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging.
 - Open `workstreams/` when the question is about current priorities, debugging themes, or historical project patterns.
 - Open `process/` when drafting messages, standups, Jira notes, or deciding how to update memory.

ai/context/ios/current-practices.md

@@ -0,0 +1,62 @@
+# Current iOS And Swift Practices
+
+## Goal
+
+Keep Swift/iOS answers modern without turning the workspace into stale API documentation.
+
+---
+
+## Currentness Rule
+
+For version-sensitive recommendations, verify against official sources before presenting as current best practice.
+
+Prefer:
+
+- Apple Developer Documentation
+- Swift.org / docs.swift.org
+- official WWDC materials when API behavior or migration guidance matters
+
+Avoid relying only on memory for:
+
+- newest SwiftUI APIs
+- Observation / data-flow migration guidance
+- Swift Testing availability or migration advice
+- Swift concurrency behavior
+- Xcode or iOS version-specific recommendations
+
+---
+
+## Stable Defaults
+
+- Prefer simple, testable Swift over clever abstractions.
+- Prefer structured concurrency over ad-hoc callback or detached-task patterns when the deployment target and codebase support it.
+- Keep UI state changes on the main actor.
+- Avoid recommending new APIs until deployment target and project constraints are known.
+- For SwiftUI, separate pure view composition from side effects and navigation/workflow coordination.
+- For testing, use the framework already adopted by the codebase unless the user explicitly asks about migration.
+
+---
+
+## Testing Guidance
+
+- Apple positions Swift Testing as a modern option for unit tests in Xcode 16 and later.
+- XCTest remains relevant, especially for UI tests, performance tests, and existing test suites.
+- Do not recommend wholesale migration from XCTest unless the project constraints support it.
+
+---
+
+## SwiftUI Guidance
+
+- Observation can be adopted incrementally; do not assume a project can immediately replace all `ObservableObject` usage.
+- In SwiftUI code review, focus on data ownership, lifecycle, invalidation scope, navigation boundaries, and side effects.
+- Avoid introducing `@StateObject`, `@ObservedObject`, `@State`, or `@Observable` recommendations without first identifying ownership and deployment constraints.
+
+---
+
+## Source Anchors
+
+- SwiftUI documentation: `https://developer.apple.com/documentation/swiftui`
+- Observation migration: `https://developer.apple.com/documentation/swiftui/migrating-from-the-observable-object-protocol-to-the-observable-macro`
+- Swift Testing: `https://developer.apple.com/documentation/testing`
+- XCTest: `https://developer.apple.com/documentation/xctest`
+- Swift language: `https://developer.apple.com/swift/`

ai/context/ios/index.md

@@ -0,0 +1,23 @@
+# iOS And Swift Context
+
+## Goal
+
+Help the agent answer Swift and iOS programming questions with current best practices while still respecting Fidelity/XFlow project constraints.
+
+---
+
+## Files
+
+- [current-practices.md](./current-practices.md)
+  Rules for staying current with Apple and Swift best practices.
+
+- [project-swift-guidance.md](./project-swift-guidance.md)
+  Fidelity-specific guidance for applying Swift/iOS advice in this workspace.
+
+---
+
+## Usage
+
+- Use these files before answering Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging questions.
+- When a recommendation depends on current Apple APIs, prefer official Apple or Swift documentation before making strong claims.
+- Keep project constraints visible: XFlow is backend-driven, Fid4 is consumer validation, and REST/GraphQL migration constraints may affect architecture.

ai/context/ios/project-swift-guidance.md

@@ -0,0 +1,37 @@
+# Project Swift Guidance
+
+## Goal
+
+Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker, and FTFrameworks environment.
+
+---
+
+## Fidelity-Specific Constraints
+
+- XFlow is backend-driven; UI behavior may be service/configuration driven, not purely local Swift code.
+- Fid4 is the real consumer validation target for many issues.
+- XFlowViewMaker and FTFrameworks can affect whether a fix is visible in Fid4.
+- REST migration constraints still matter; do not assume REST is active by default.
+- Some work happens behind feature flags, especially risky consumer-impact changes.
+
+---
+
+## SwiftUI / XFlow Priorities
+
+- Treat modal presentation, dismissal sequencing, and lifecycle boundaries as high-risk areas.
+- Be careful when removing UIKit bridges such as `UIHostingController`; preserve consumer behavior and rollout safety.
+- When discussing SwiftUI architecture, include how the change affects:
+  - backend-driven flow rendering
+  - consumer app integration
+  - feature flags
+  - validation in Fid4
+  - UIKit/SwiftUI parity
+
+---
+
+## Answering Rules
+
+- If the user asks a general Swift question, answer generally but include a Fidelity/XFlow note when relevant.
+- If the user asks about a code change, separate modern best practice from what is safe for the current project.
+- If codebase constraints are unknown, say what must be confirmed: deployment target, Xcode version, module ownership, feature flag path, and consumer validation path.
+- For manager-ready explanations, connect the technical recommendation to scope, risk, and validation.

opencode.json

@@ -43,6 +43,9 @@
     "./README.md",
     "./ai/context/index.md",
     "./ai/context/project.md",
+    "./ai/context/ios/index.md",
+    "./ai/context/ios/current-practices.md",
+    "./ai/context/ios/project-swift-guidance.md",
     "./ai/context/systems/index.md",
     "./ai/context/workstreams/index.md",
     "./ai/context/process/communication.md",