Add project-knowledge structure and templates
- Introduced new maps for navigating project knowledge, including "Current Work," "Fidelity Domain," "Fidelity Apps," "Work Items," and "People." - Created base files for daily notes, decisions, people, systems, work items, and workstreams with defined properties and views. - Developed templates for daily notes, decisions, meeting notes, persons, systems, work items, and workstreams to standardize documentation. - Updated scripts and prompts to reflect the new project-knowledge directory structure. - Removed outdated onboarding and start-here documents, consolidating relevant information into the new maps. - Ensured all references in workflows and scripts point to the new project-knowledge paths.
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
---
|
||||
type: guidance
|
||||
project: fidelity
|
||||
status: active
|
||||
updated: 2026-04-17
|
||||
tags:
|
||||
- ios
|
||||
- cocoapods
|
||||
- dependencies
|
||||
- fidelity
|
||||
---
|
||||
# CocoaPods Dependency Management
|
||||
|
||||
## Goal
|
||||
|
||||
Help the agent reason correctly about CocoaPods behavior, private podspec repos, and release propagation in the Fidelity iOS ecosystem.
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters Here
|
||||
|
||||
- CocoaPods is a core part of how XFlowSDK changes reach XFlowViewMaker, FTFrameworks, and Fid4.
|
||||
- Many apparent SDK or consumer issues are actually dependency-resolution or published-podspec issues.
|
||||
- The workspace should treat CocoaPods knowledge as part of normal investigation and release reasoning, not as an edge case.
|
||||
|
||||
---
|
||||
|
||||
## Fidelity-Specific Context
|
||||
|
||||
- XFlowSDK releases publish artifacts and podspec updates that downstream consumers adopt through CocoaPods.
|
||||
- XFlowViewMaker, FTAccountOpen, FTTransfer, and Fid4 propagation all depend on correct podspec and resolver behavior.
|
||||
- The effective dependency constraint can come from the published podspec repo layer, not only from the source repo that developers inspect first.
|
||||
- Fid4 currently does not keep `Podfile.lock` in Git, which weakens reproducibility and makes published podspec changes more operationally significant.
|
||||
|
||||
---
|
||||
|
||||
## Agent Rules
|
||||
|
||||
- When a newly published dependency does not resolve in Fid4, check CocoaPods resolution before assuming the code change failed.
|
||||
- Distinguish these layers:
|
||||
- source repo podspec or helper code
|
||||
- published private podspec repo
|
||||
- consumer `Podfile`
|
||||
- local/pipeline lockfile state
|
||||
- Do not assume FTFrameworks source tells the whole truth about the active dependency graph.
|
||||
- Treat private podspec repo edits as high-signal release-path behavior that may explain why local or pipeline resolution differs from expectations.
|
||||
- When giving advice, separate:
|
||||
- what fixed the immediate unblock
|
||||
- what is healthy long-term dependency management
|
||||
|
||||
---
|
||||
|
||||
## CocoaPods Best-Practice Anchors
|
||||
|
||||
- CocoaPods podspecs are expected to declare dependency requirements explicitly.
|
||||
- CocoaPods documentation recommends the optimistic operator `~>` because it provides version control without being overly restrictive.
|
||||
- Overly restrictive dependency requirements can block compatibility.
|
||||
- Removing dependency constraints entirely can weaken compatibility guarantees and make transitive resolution less predictable.
|
||||
- `pod install` is the normal command after dependency-definition changes; `pod update` is for intentionally updating pod versions.
|
||||
- `Podfile.lock` is important for reproducible installs and should normally be committed.
|
||||
|
||||
---
|
||||
|
||||
## Current Project Caution
|
||||
|
||||
- In this project, removing the XFlowViewMaker version reference from published `FTAccountOpen` and `FTTransfer` podspecs unblocked Fid4 resolution.
|
||||
- That should be understood as the current operational fix, not automatically as the ideal dependency-management pattern.
|
||||
- Because `Podfile.lock` is not committed in Fid4, broad podspec-repo edits can silently change future resolutions more than they should in a healthier CocoaPods setup.
|
||||
|
||||
---
|
||||
|
||||
## What Good Answers Should Include
|
||||
|
||||
- Whether the issue is in source code, published specs, or consumer resolution
|
||||
- Whether `pod install`, `pod install --repo-update`, or `pod update` is the appropriate command for the stated goal
|
||||
- Whether the current fix improves compatibility or only removes guardrails
|
||||
- Whether the result is reproducible or vulnerable to future resolver drift
|
||||
- Whether the advice is a short-term unblock or a durable recommendation
|
||||
94
project-knowledge/03-context/ios/current-practices.md
Normal file
94
project-knowledge/03-context/ios/current-practices.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
type: guidance
|
||||
project: fidelity
|
||||
status: active
|
||||
updated: 2026-04-16
|
||||
tags:
|
||||
- ios
|
||||
- fidelity
|
||||
---
|
||||
# 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
|
||||
- CocoaPods, podspec, private specs repo, trunk/CDN, or dependency-resolution behavior
|
||||
- Swift Package Manager migration or package-resolution behavior
|
||||
- CI/build tooling behavior that may depend on current toolchain versions
|
||||
- claims that something is a "bad practice" when the answer depends on ecosystem status, migration cost, or project constraints
|
||||
|
||||
---
|
||||
|
||||
## Technical Verification Rule
|
||||
|
||||
For programming concepts tied to project decisions, the agent should behave like a senior engineer:
|
||||
|
||||
- distinguish stable engineering principles from ecosystem-specific guidance
|
||||
- verify current tool behavior with primary documentation when the topic is version-sensitive
|
||||
- separate general best practice from project-safe recommendation
|
||||
- avoid blanket statements such as "CocoaPods is bad practice" without context
|
||||
- explain tradeoffs: maintenance status, migration cost, consumer integration risk, release propagation, and validation path
|
||||
- suggest workspace improvements when a recurring answer-quality gap appears
|
||||
|
||||
For Fidelity, dependency tooling is project-relevant because XFlowSDK, XFlowViewMaker, FTFrameworks, and Fid4 integration can depend on published versions, podspec repos, release propagation, and consumer validation.
|
||||
|
||||
---
|
||||
|
||||
## 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/`
|
||||
- CocoaPods Build with CocoaPods: `https://guides.cocoapods.org/making/`
|
||||
- CocoaPods Specs and Specs Repo: `https://guides.cocoapods.org/making/specs-and-specs-repo.html`
|
||||
- CocoaPods Private Pods: `https://guides.cocoapods.org/making/private-cocoapods`
|
||||
- CocoaPods trunk read-only plan: `https://blog.cocoapods.org/CocoaPods-Specs-Repo/`
|
||||
36
project-knowledge/03-context/ios/index.md
Normal file
36
project-knowledge/03-context/ios/index.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
type: guidance-index
|
||||
project: fidelity
|
||||
status: active
|
||||
updated: 2026-04-17
|
||||
tags:
|
||||
- ios
|
||||
- fidelity
|
||||
---
|
||||
# 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.
|
||||
|
||||
- [cocoapods-dependency-management.md](./cocoapods-dependency-management.md)
|
||||
CocoaPods, private podspec repo, and dependency-resolution guidance for Fidelity release and consumer integration work.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
- Use these files before answering Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging questions.
|
||||
- Use the CocoaPods guidance whenever the question touches release propagation, podspecs, dependency conflicts, Fid4 resolution, or FTFrameworks consumer updates.
|
||||
- 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.
|
||||
50
project-knowledge/03-context/ios/project-swift-guidance.md
Normal file
50
project-knowledge/03-context/ios/project-swift-guidance.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
type: guidance
|
||||
project: fidelity
|
||||
status: active
|
||||
updated: 2026-04-17
|
||||
tags:
|
||||
- ios
|
||||
- fidelity
|
||||
---
|
||||
# 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.
|
||||
- CocoaPods and private podspec-repo behavior are part of the real integration surface, not just build tooling details.
|
||||
- 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.
|
||||
- If the work touches dependency propagation, published specs, or consumer upgrade behavior, explicitly include CocoaPods and podspec-repo reasoning instead of treating them as secondary operational noise.
|
||||
- If the user asks whether CocoaPods, podspec repositories, or dependency propagation is good/bad practice, corroborate with current CocoaPods/Apple/Swift documentation and then adapt the recommendation to Fidelity's release path.
|
||||
- Do not recommend replacing CocoaPods with SPM just because SPM is modern; first identify current integration constraints, private specs usage, release ownership, consumer app expectations, and migration cost.
|
||||
- For manager-ready explanations, connect the technical recommendation to scope, risk, and validation.
|
||||
Reference in New Issue
Block a user