fidelity-ai-workspace/AGENTS.md

Fidelity AI Workspace Rules

This repository is a companion workspace for Fidelity iOS work, not the product codebase.

OpenCode should treat this project as a persistent context layer used to:

• keep current project state accurate
• capture durable information from daily work
• draft standups and Mattermost messages
• improve communication for the current manager or stakeholder in natural professional English

Hot Context

Keep the always-loaded context small. The hot set is:

• profiles/fidelity/profile.md
• agent-memory/behavior/agent-behavior.md
• agent-memory/behavior/learning-sessions.md
• agent-memory/memory/promotion-rules.md
• agent-memory/integrations/technical-verification.md
• agent-memory/workflows/ai-to-ai-prompting.md
• project-knowledge/00-start/start-here.md
• project-knowledge/01-current/current-work.md
• project-knowledge/01-current/work-items.md
• project-knowledge/03-context/project.md
• project-knowledge/03-context/process/communication.md
• project-knowledge/03-context/ios/index.md
• project-knowledge/03-context/ios/project-swift-guidance.md
• project-knowledge/04-people/manager.md
• project-knowledge/04-people/index.md

Load everything else lazily when the task actually needs it.

Do not preemptively load broad context sets, all work-item files, or all process notes unless the current task clearly requires them.

Required Behavior

• Assume the workspace may contain stale context until checked.
• Treat project-knowledge/ as the canonical clean project memory for humans and AI. Treat agent-memory/ as agent operating memory. Treat ai/inbox/ as raw evidence only.
• Treat scripts/memory/ as the project-agnostic interface for creating notes, searching memory, querying Bases, and running project knowledge health checks.
• Treat scripts/obsidian/ as the current Obsidian adapter, not as the core memory abstraction.
• Keep Obsidian Bases clean: templates in project-knowledge/09-templates/ must not be treated as real notes, and role mapping files such as project-knowledge/04-people/manager.md must not be typed as people.
• Maintain useful project-note properties when editing canonical notes, especially work-item relationships (systems, workstreams, people, related) and daily note fields (focus, work-items, blockers).
• Before answering questions that depend on current work state, inspect project-knowledge/01-current/current-work.md and the latest relevant daily note under project-knowledge/06-daily/.
• Prefer lazy loading over eager loading. Pull in only the smallest relevant files for the active task.
• For Mattermost evidence, prefer the local proxy mirror under ai/inbox/mattermost-mirror/ when present. Use scripts/mattermost-proxy/read-context.py or mirror views (latest.*, by-date/, channels/, threads/) before falling back to legacy ai/inbox/mattermost-latest.md or scripts/mattermost/generated/ artifacts.
• If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, use the explicit latest-message flow and answer from the freshest refreshed evidence; the proxy mirror is primary when available.
• If automatic refresh is uncertain and the proxy mirror is not available, run the Mattermost sync command, then answer from the refreshed inbox only.
• Treat latest-message flows as read-first. Report memory update candidates, but do not edit canonical memory from that command unless the user explicitly asks to promote the fact.
• For learning-style questions, answer from known context and verified facts only; label unknowns, assumptions, and inferences instead of inventing missing details.
• For learning sessions, prioritize durable architecture, process, ownership, debugging strategy, release mechanics, domain concepts, and decision rules over transient ticket status.
• If the user asks what to clarify, ask 3 to 5 high-leverage questions that would help a senior engineer ramp into the project, and include why each matters.
• Ask a concise clarification question when missing context materially changes the answer.
• If the user corrects or teaches the agent during a learning session, update the smallest correct canonical file or behavior surface when that learning should persist.
• For any meaningful prompt, decide whether the interaction introduces or corrects project memory.
• For analysis, review, translation, or drafting requests, answer first unless a memory update is required to avoid losing a clear durable fact.
• Do not create new canonical notes before answering unless the user asked to save the information, the destination is obvious, and the write is small and non-blocking.
• Prefer updating existing canonical files over creating new files during the critical path of a user-facing answer.
• If a sync command, extraction script, or inbox refresh fails, do not update logs, state, or context files from that failed attempt.
• Treat sync failures as operational errors, not project context.
• If a patch or edit verification fails while making a non-essential memory update, stop retrying and return the user-facing answer with the failed target noted.
• mattermost-sync should automatically promote high-confidence project facts without asking what to promote.
• Prefer project-knowledge/06-daily/ as the default destination for new Mattermost-derived facts.
• Promote to project-knowledge/01-current/current-work.md only when the fact materially changes active work over the next few days.
• Keep explicit Jira IDs and approved titles visible in project-knowledge/02-work-items/ and summarize active items in project-knowledge/01-current/work-items.md when they are useful for future standups or manager updates.
• Promote to project-knowledge/03-context/project.md only when the fact changes durable project understanding.
• When a repeatedly mentioned person becomes relevant to project flow, create or update a file under project-knowledge/04-people/.
• Keep role-to-person mapping explicit in project-knowledge/04-people/manager.md and the roster in project-knowledge/04-people/index.md.
• Never promote tooling chatter, sync status, or generic conversation noise.
• Direct user prompts are also memory sources. Do not limit memory updates to explicit sync commands.
• If a new prompt corrects prior understanding, update the canonical file directly instead of keeping both versions alive.
• Do not ask what should be saved when the correct destination is already clear.
• If the user provides durable new facts, update the appropriate context files instead of leaving the new information only in chat history.
• When the prompt is primarily asking for analysis of a screenshot, message, or document, do not interrupt the answer to perform proactive note creation unless that persistence is the explicit goal.
• When creating a new canonical note from a known type, prefer scripts/memory/memory.sh create <type> <slug> [title] so type-to-folder routing stays centralized.
• If the Obsidian CLI adapter fails, fall back to direct Markdown operations and treat the failure as tooling status, not project context.
• If a previous context file is now stale or inaccurate, update that file directly.
• 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 project-knowledge/03-context/systems/, project-knowledge/03-context/workstreams/, or project-facing project-knowledge/03-context/process/ instead of overloading project-knowledge/03-context/project.md.
• When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use project-knowledge/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 agent-memory/workflows/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

When drafting or polishing messages:

• use Context, Observation, Action when appropriate
• clarify auth state when relevant
• separate external reports from regressions
• preserve technical meaning while improving English