From bbac48417063800e35b55c19abacbb5baed1f5be Mon Sep 17 00:00:00 2001 From: "david.delagneau" Date: Tue, 14 Apr 2026 14:14:23 -0600 Subject: [PATCH] feat: Add iOS and Swift context files and guidelines for answering programming questions --- .opencode/agents/fidelity.md | 2 + .opencode/commands/fidelity-context.md | 3 + .opencode/commands/swift-help.md | 36 +++++++++++ .opencode/plugins/fidelity-compaction.js | 3 + .opencode/skills/ios-swift-answering/SKILL.md | 27 ++++++++ .../skills/ios-testing-strategy/SKILL.md | 34 ++++++++++ .../skills/swiftui-xflow-review/SKILL.md | 31 ++++++++++ AGENTS.md | 5 ++ README.md | 1 + ai/AGENTS.md | 2 + ai/context/index.md | 9 +++ ai/context/ios/current-practices.md | 62 +++++++++++++++++++ ai/context/ios/index.md | 23 +++++++ ai/context/ios/project-swift-guidance.md | 37 +++++++++++ opencode.json | 3 + 15 files changed, 278 insertions(+) create mode 100644 .opencode/commands/swift-help.md create mode 100644 .opencode/skills/ios-swift-answering/SKILL.md create mode 100644 .opencode/skills/ios-testing-strategy/SKILL.md create mode 100644 .opencode/skills/swiftui-xflow-review/SKILL.md create mode 100644 ai/context/ios/current-practices.md create mode 100644 ai/context/ios/index.md create mode 100644 ai/context/ios/project-swift-guidance.md diff --git a/.opencode/agents/fidelity.md b/.opencode/agents/fidelity.md index aaca99e..02381e0 100644 --- a/.opencode/agents/fidelity.md +++ b/.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. diff --git a/.opencode/commands/fidelity-context.md b/.opencode/commands/fidelity-context.md index 368f1ca..f8f7b1d 100644 --- a/.opencode/commands/fidelity-context.md +++ b/.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 diff --git a/.opencode/commands/swift-help.md b/.opencode/commands/swift-help.md new file mode 100644 index 0000000..5d2bfda --- /dev/null +++ b/.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 diff --git a/.opencode/plugins/fidelity-compaction.js b/.opencode/plugins/fidelity-compaction.js index 8803317..84a6668 100644 --- a/.opencode/plugins/fidelity-compaction.js +++ b/.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", diff --git a/.opencode/skills/ios-swift-answering/SKILL.md b/.opencode/skills/ios-swift-answering/SKILL.md new file mode 100644 index 0000000..5f16c09 --- /dev/null +++ b/.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. diff --git a/.opencode/skills/ios-testing-strategy/SKILL.md b/.opencode/skills/ios-testing-strategy/SKILL.md new file mode 100644 index 0000000..5f017f1 --- /dev/null +++ b/.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. diff --git a/.opencode/skills/swiftui-xflow-review/SKILL.md b/.opencode/skills/swiftui-xflow-review/SKILL.md new file mode 100644 index 0000000..125038d --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index f73bce2..5d13de0 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index a56fcca..795edef 100644 --- a/README.md +++ b/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 diff --git a/ai/AGENTS.md b/ai/AGENTS.md index a06fca8..7473d7f 100644 --- a/ai/AGENTS.md +++ b/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: diff --git a/ai/context/index.md b/ai/context/index.md index 1ac3c7d..6ab2b92 100644 --- a/ai/context/index.md +++ b/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. diff --git a/ai/context/ios/current-practices.md b/ai/context/ios/current-practices.md new file mode 100644 index 0000000..f11695e --- /dev/null +++ b/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/` diff --git a/ai/context/ios/index.md b/ai/context/ios/index.md new file mode 100644 index 0000000..fab0c16 --- /dev/null +++ b/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. diff --git a/ai/context/ios/project-swift-guidance.md b/ai/context/ios/project-swift-guidance.md new file mode 100644 index 0000000..6a83199 --- /dev/null +++ b/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. diff --git a/opencode.json b/opencode.json index 9945ac8..cc73a79 100644 --- a/opencode.json +++ b/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",