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

Always-Loaded Context

The detailed operating rules live in:

• vault/00-start/start-here.md
• vault/00-start/workspace-architecture.md
• vault/01-current/current-work.md
• vault/01-current/work-items.md
• vault/03-context/project.md
• vault/03-context/ios/index.md
• vault/03-context/ios/current-practices.md
• vault/03-context/ios/project-swift-guidance.md
• vault/03-context/systems/index.md
• vault/03-context/workstreams/index.md
• vault/03-context/process/communication.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
• core/integrations/memory-vault-model.md
• vault/04-people/manager.md
• vault/04-people/index.md
• vault/02-work-items/index.md

These are also loaded through opencode.json.

Required Behavior

• Assume the workspace may contain stale context until checked.
• Treat vault/ as the canonical clean memory for humans and AI. Treat ai/inbox/ as raw evidence only.
• Treat scripts/memory/ as the project-agnostic interface for creating notes, searching memory, querying Bases, and running vault health checks.
• Treat scripts/obsidian/ as the current Obsidian adapter, not as the core memory abstraction.
• Keep Obsidian Bases clean: templates in vault/09-templates/ must not be treated as real notes, and role mapping files such as vault/04-people/manager.md must not be typed as people.
• Maintain useful vault 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 vault/01-current/current-work.md and the latest relevant daily note under vault/06-daily/.
• If ai/inbox/mattermost-latest.md exists, inspect it for fresher communication context before answering standup, status, or manager-message prompts.
• If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, synchronize Mattermost first instead of relying on existing inbox context.
• If automatic refresh is uncertain, use the explicit latest-message flow: run the Mattermost sync command, then answer from the refreshed inbox only.
• 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.
• 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.
• mattermost-sync should automatically promote high-confidence project facts without asking what to promote.
• Prefer vault/06-daily/ as the default destination for new Mattermost-derived facts.
• Promote to vault/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 vault/02-work-items/ and summarize active items in vault/01-current/work-items.md when they are useful for future standups or manager updates.
• Promote to vault/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 vault/04-people/.
• Keep role-to-person mapping explicit in vault/04-people/manager.md and the roster in vault/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 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 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 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.

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