diff --git a/.opencode/agents/fidelity.md b/.opencode/agents/fidelity.md index 44a6afc..ecca652 100644 --- a/.opencode/agents/fidelity.md +++ b/.opencode/agents/fidelity.md @@ -58,5 +58,8 @@ Behavior rules: - 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 `vault/03-context/ios/`. +- When answering programming, dependency-management, package-manager, CI/build, testing, or architecture-practice questions, verify with primary/current documentation when the topic may be outdated, disputed, version-sensitive, or project-critical. +- For CocoaPods, podspecs, private spec repos, trunk/CDN behavior, SPM, Xcode, Swift, and Apple frameworks, do not rely only on model memory before giving strong advice. - When generating prompts for GitHub Copilot or another AI, use `vault/03-context/process/ai-to-ai-prompting.md` and the `copilot-prompt-engineering` skill. - 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. +- Act as an agent, not only as a chat assistant: when a repeated weakness appears in output quality, proactively suggest or apply a workspace-level improvement. diff --git a/.opencode/agents/workspace.md b/.opencode/agents/workspace.md index 2f99d46..d5ee81d 100644 --- a/.opencode/agents/workspace.md +++ b/.opencode/agents/workspace.md @@ -31,6 +31,8 @@ Behavior rules: - If an integration or sync command fails, do not update project memory from that failure. - Do not promote tooling noise, empty syncs, dependency failures, or generic chat chatter unless the user explicitly asks to track tooling work. - Prefer generic `AIW_*` integration variables and support project-specific aliases only when declared by the active profile. +- For technical advice about programming concepts, dependency tooling, package managers, CI/build systems, testing frameworks, or changing best practices, verify against primary/current documentation before making strong claims. +- Treat recurring quality gaps as workspace-maintenance signals and update commands, agents, skills, prompts, or process notes when the improvement should persist. - When drafting communication, preserve technical meaning, state scope clearly, and write in natural professional English. Memory destinations: diff --git a/.opencode/commands/fidelity-context.md b/.opencode/commands/fidelity-context.md index 11b117a..a45d0ca 100644 --- a/.opencode/commands/fidelity-context.md +++ b/.opencode/commands/fidelity-context.md @@ -21,6 +21,7 @@ Use these files as the baseline context: @vault/07-maps/people.md @vault/03-context/project.md @vault/03-context/process/communication.md +@vault/03-context/process/technical-verification.md @vault/03-context/process/ai-to-ai-prompting.md @vault/03-context/process/jira-story-rules.md @vault/03-context/process/workspace-model.md diff --git a/.opencode/commands/swift-help.md b/.opencode/commands/swift-help.md index 5ce813b..7274738 100644 --- a/.opencode/commands/swift-help.md +++ b/.opencode/commands/swift-help.md @@ -9,6 +9,7 @@ Read: @vault/03-context/ios/index.md @vault/03-context/ios/current-practices.md @vault/03-context/ios/project-swift-guidance.md +@vault/03-context/process/technical-verification.md @vault/03-context/project.md @vault/03-context/systems/index.md @vault/03-context/workstreams/index.md @@ -23,7 +24,7 @@ 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. +- If current Apple API, Swift, CocoaPods, SPM, Xcode, CI/build, or testing behavior matters, verify against official/primary 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. diff --git a/.opencode/commands/workspace-context.md b/.opencode/commands/workspace-context.md index 4b0e8bb..f722d27 100644 --- a/.opencode/commands/workspace-context.md +++ b/.opencode/commands/workspace-context.md @@ -25,6 +25,7 @@ Read active workspace memory: @vault/07-maps/people.md @vault/03-context/project.md @vault/03-context/process/communication.md +@vault/03-context/process/technical-verification.md @vault/03-context/process/context-maintenance.md @vault/03-context/process/workspace-model.md @vault/03-context/process/agent-memory-rules.md diff --git a/.opencode/skills/ios-swift-answering/SKILL.md b/.opencode/skills/ios-swift-answering/SKILL.md index d42a0be..f33b870 100644 --- a/.opencode/skills/ios-swift-answering/SKILL.md +++ b/.opencode/skills/ios-swift-answering/SKILL.md @@ -13,7 +13,7 @@ Use this skill for Swift, SwiftUI, iOS architecture, concurrency, testing, or de 1. Identify whether the question is general Swift/iOS or Fidelity-specific. 2. Read `vault/03-context/ios/current-practices.md` for currentness rules. 3. Read `vault/03-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. +4. If the answer depends on current Apple APIs, Xcode versions, dependency tooling, package-manager behavior, testing frameworks, or migration guidance, verify with official/primary documentation before making strong claims. 5. Separate: - current best practice - project-safe recommendation @@ -24,4 +24,5 @@ Use this skill for Swift, SwiftUI, iOS architecture, concurrency, testing, or de - 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. +- Do not characterize CocoaPods, SPM, podspec repos, trunk/CDN behavior, CI/build behavior, or testing framework practices as good or bad practice without corroborating current primary docs when the recommendation matters. - Mention tradeoffs and validation path when relevant. diff --git a/AGENTS.md b/AGENTS.md index 9a34190..faf61ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,7 @@ The detailed operating rules live in: - `vault/03-context/systems/index.md` - `vault/03-context/workstreams/index.md` - `vault/03-context/process/communication.md` +- `vault/03-context/process/technical-verification.md` - `vault/03-context/process/ai-to-ai-prompting.md` - `vault/03-context/process/workspace-model.md` - `vault/03-context/process/memory-promotion-rules.md` @@ -73,8 +74,11 @@ These are also loaded through `opencode.json`. - Keep changes concise and auditable. - When the topic is architectural or historical, prefer updating the relevant file under `vault/03-context/systems/`, `vault/03-context/workstreams/`, or `vault/03-context/process/` instead of overloading `vault/03-context/project.md`. - When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `vault/03-context/ios/` and the local OpenCode iOS skills before answering. +- When the user asks about programming concepts, dependency tooling, package managers, CI/build tooling, testing frameworks, or practices that may be outdated or opinion-sensitive, verify against primary/current documentation before making strong claims. +- For CocoaPods, podspecs, private specs repos, trunk/CDN behavior, Swift Package Manager, Xcode, Swift, Apple frameworks, and similar project-linked tooling, do not rely only on memory. - When the user asks for a prompt for another AI, GitHub Copilot, or the Fidelity development machine, use `vault/03-context/process/ai-to-ai-prompting.md` and generate a self-contained prompt. - 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. +- Be aware that this is an agentic workspace. If a recurring gap appears in answers, propose and when appropriate apply a workspace improvement to commands, agents, skills, prompts, or process notes. ## Communication diff --git a/core/memory/operational-memory.md b/core/memory/operational-memory.md index 0afcf29..dd6ff1e 100644 --- a/core/memory/operational-memory.md +++ b/core/memory/operational-memory.md @@ -172,3 +172,12 @@ Examples: - memory routing correction -> update memory rules and context-maintenance guidance The daily log may preserve evidence, but reusable behavior must live in the command, prompt, skill, agent, or knowledge file that enforces it. + +The agent should also identify recurring quality gaps proactively. If an answer reveals that the workspace lacks a rule, source anchor, command behavior, skill guidance, or memory model needed for better future output, the agent should propose the improvement and apply it when the correct destination is clear. + +For technical topics, recurring gaps often belong in: + +- domain-specific guidance under `vault/03-context/` +- reusable skills under `.opencode/skills/` +- agent behavior rules under `.opencode/agents/` or `AGENTS.md` +- source anchors for official/current documentation diff --git a/opencode.json b/opencode.json index 35207f6..b5cc461 100644 --- a/opencode.json +++ b/opencode.json @@ -60,6 +60,7 @@ "./vault/07-maps/people.md", "./vault/03-context/project.md", "./vault/03-context/process/communication.md", + "./vault/03-context/process/technical-verification.md", "./vault/03-context/process/ai-to-ai-prompting.md", "./vault/03-context/process/jira-story-rules.md", "./vault/03-context/process/context-maintenance.md", diff --git a/vault/00-start/start-here.md b/vault/00-start/start-here.md index be21b76..74bf9f3 100644 --- a/vault/00-start/start-here.md +++ b/vault/00-start/start-here.md @@ -73,6 +73,7 @@ If you are new to this project, read: - [Agent Memory Rules](../03-context/process/agent-memory-rules.md) - [Memory Promotion Rules](../03-context/process/memory-promotion-rules.md) - [Communication Rules](../03-context/process/communication-rules.md) +- [Technical Verification](../03-context/process/technical-verification.md) - [Context Maintenance](../03-context/process/context-maintenance.md) - [Workspace Architecture](workspace-architecture.md) - Memory interface: `scripts/memory/` diff --git a/vault/03-context/ios/current-practices.md b/vault/03-context/ios/current-practices.md index 5e077b7..4d7e2ad 100644 --- a/vault/03-context/ios/current-practices.md +++ b/vault/03-context/ios/current-practices.md @@ -32,6 +32,25 @@ Avoid relying only on memory for: - 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. --- @@ -69,3 +88,7 @@ Avoid relying only on memory for: - 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/` diff --git a/vault/03-context/ios/project-swift-guidance.md b/vault/03-context/ios/project-swift-guidance.md index f95a8b5..1f9fcaa 100644 --- a/vault/03-context/ios/project-swift-guidance.md +++ b/vault/03-context/ios/project-swift-guidance.md @@ -45,4 +45,6 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker - 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. diff --git a/vault/03-context/process/index.md b/vault/03-context/process/index.md index c173d20..732d9d4 100644 --- a/vault/03-context/process/index.md +++ b/vault/03-context/process/index.md @@ -14,6 +14,9 @@ tags: - [communication.md](./communication.md) How to frame technical updates and external communication. +- [technical-verification.md](./technical-verification.md) + How to verify current engineering concepts and avoid stale best-practice claims. + - [ai-to-ai-prompting.md](./ai-to-ai-prompting.md) How to generate prompts for GitHub Copilot or another AI on the Fidelity development machine. diff --git a/vault/03-context/process/technical-verification.md b/vault/03-context/process/technical-verification.md new file mode 100644 index 0000000..a69b1c2 --- /dev/null +++ b/vault/03-context/process/technical-verification.md @@ -0,0 +1,83 @@ +--- +type: process +project: fidelity +status: active +updated: 2026-04-17 +tags: + - process + - engineering + - verification +--- +# Technical Verification + +## Goal + +Ensure the agent gives senior-engineer technical advice instead of relying on stale model memory or generic best-practice claims. + +--- + +## When To Verify + +Verify against primary/current documentation before making strong claims about: + +- dependency managers and package managers +- CocoaPods, podspecs, private specs repos, trunk/CDN behavior, and migration strategy +- Swift Package Manager behavior or migration strategy +- Xcode, Swift, SwiftUI, Swift concurrency, Swift Testing, XCTest, or Apple framework behavior +- CI/build systems and release propagation +- security, authentication, networking, or migration practices +- any claim that a pattern is a bad practice when project constraints may change the recommendation + +--- + +## Source Priority + +Prefer: + +- official vendor documentation +- language or framework documentation +- official migration guides +- source repository documentation when it is the canonical project source +- current project memory when the question is project-specific + +Use blogs, forum posts, or third-party guides only as supporting context, not as the primary basis for a strong recommendation. + +--- + +## Answering Pattern + +For technical recommendations: + +1. State what is known from workspace context. +2. Verify current external behavior when the topic is version-sensitive or disputed. +3. Separate general best practice from project-safe recommendation. +4. Explain tradeoffs and validation path. +5. If context is missing, ask the smallest material clarification question. + +--- + +## Bad Practice Claims + +Avoid blanket claims such as: + +- "CocoaPods is bad practice" +- "SPM is always better" +- "This architecture is an anti-pattern" +- "This should be removed" + +Instead explain: + +- what risk the pattern introduces +- whether the risk is current or theoretical +- whether the project has constraints that justify it +- what a safer migration path would look like + +--- + +## Agentic Self-Improvement + +The agent should be aware it is maintaining a workspace, not just answering chat prompts. + +If a conversation reveals a recurring gap in technical quality, source verification, command behavior, or memory routing, the agent should propose or apply a workspace improvement in the correct file. + +Do not store tool failures or one-off uncertainty as project facts. Store reusable rules and source anchors when they improve future technical answers.