feat: Add Fidelity workspace agent and context management commands

- Introduced a primary agent for the Fidelity AI Workspace to maintain context and support daily engineering tasks.
- Created commands for loading workspace context, drafting updates for Jeff, and logging daily notes.
- Implemented translation and standup generation commands to enhance communication clarity.
- Developed a compaction plugin to preserve essential workspace context during sessions.
- Established a structured approach for managing project knowledge, communication rules, and decision-making processes.
- Updated README and project structure to reflect new workflows and usage guidelines.

.opencode/agents/fidelity.md

@@ -0,0 +1,24 @@
+---
+description: Fidelity workspace agent for context-aware daily engineering support
+mode: primary
+temperature: 0.1
+---
+
+You are the primary OpenCode agent for the Fidelity AI Workspace.
+
+Your job is not only to answer prompts, but to keep the workspace context accurate over time.
+
+Behavior rules:
+
+- Treat `README.md`, `ai/context/`, `ai/state/`, `knowledge/`, and `ai/logs/` as the persistent memory of the project.
+- Before answering a prompt that depends on current state, verify the latest relevant files instead of relying only on conversation history.
+- When the user provides new durable information, update the right workspace files before or while answering.
+- If existing context is stale, correct it directly instead of leaving conflicting versions.
+- Promote information carefully:
+  - daily facts go to `ai/logs/YYYY-MM-DD.md`
+  - current priorities go to `ai/state/current.md`
+  - durable project knowledge goes to `ai/context/project.md`
+  - confirmed team or manager communication preferences go to `ai/context/people/jeff.md`
+  - confirmed decisions go to `ai/context/decisions/`
+- 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.

.opencode/commands/fidelity-context.md

@@ -0,0 +1,37 @@
+---
+description: Load Fidelity workspace context for the current session
+---
+
+Load and internalize the active context for this Fidelity workspace before answering any follow-up questions today.
+
+Use these files as the baseline context:
+
+@README.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/context/people/jeff.md
+@ai/state/current.md
+@ai/context/decisions/rest-vs-graphql.md
+@ai/context/decisions/discourse-handling.md
+@knowledge/workspace-model.md
+@knowledge/communication-rules.md
+
+Today's date:
+
+!`date +%F`
+
+Today's log, if present:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+Recent logs available:
+
+!`ls -1 ai/logs 2>/dev/null | sort | tail -n 5`
+
+Respond with:
+
+1. Current context
+2. Communication risks
+3. Missing context to capture today
+
+Keep the response concise, then wait for the next request.

.opencode/commands/jeff-update.md

@@ -0,0 +1,36 @@
+---
+description: Draft or polish a Mattermost update for Jeff
+---
+
+Draft a concise Mattermost message for Jeff in natural US English.
+
+Read:
+
+@prompts/manager-update.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/context/people/jeff.md
+@ai/state/current.md
+@knowledge/communication-rules.md
+
+Today's log, if present:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+User draft or rough notes:
+
+$ARGUMENTS
+
+Requirements:
+
+- Use Context, Observation, Action
+- Clarify scope
+- Preserve technical meaning
+- Mention auth state when relevant
+- Do not label something a regression unless the context supports it
+- Keep the result short enough for Mattermost
+
+Return:
+
+1. Final message
+2. One-line note with any assumption you had to make

.opencode/commands/log-note.md

@@ -0,0 +1,33 @@
+---
+description: Update today's log from rough notes or Mattermost context
+---
+
+Use this workspace as the source of truth for daily context maintenance.
+
+Read:
+
+@README.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/state/current.md
+
+Today's existing log, if present:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+Incorporate these new rough notes into today's log:
+
+$ARGUMENTS
+
+Instructions:
+
+- Update or create `ai/logs/$(date +%F).md`
+- Preserve concrete technical meaning
+- Capture both technical findings and communication context when relevant
+- Keep the log concise but reusable for later standups and manager updates
+- If the notes are ambiguous, normalize them without inventing facts
+
+After editing, respond with:
+
+1. What was added or clarified
+2. Any missing context still worth capturing

.opencode/commands/mattermost-translate.md

@@ -0,0 +1,23 @@
+---
+description: Translate rough Spanish engineering notes into Mattermost-ready English
+---
+
+Translate and tighten the following rough notes for Mattermost:
+
+$ARGUMENTS
+
+Read:
+
+@prompts/mattermost-translation.md
+@ai/AGENTS.md
+@ai/context/people/jeff.md
+@knowledge/communication-rules.md
+
+If relevant, use today's log for context:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+Return:
+
+1. Clean message
+2. Short assumptions note

.opencode/commands/standup.md

@@ -0,0 +1,28 @@
+---
+description: Draft a standup from the latest Fidelity workspace context
+---
+
+Generate a standup update using the latest workspace state.
+
+Read:
+
+@prompts/standup.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/state/current.md
+@knowledge/communication-rules.md
+
+Today's log, if present:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+If no log exists for today, also inspect the most recent previous log:
+
+!`latest=$(ls -1 ai/logs 2>/dev/null | sort | tail -n 1); if [ -n "$latest" ]; then echo "$latest"; cat "ai/logs/$latest"; else echo "No logs available."; fi`
+
+Return a standup that is:
+
+- specific
+- concise
+- grounded in the latest context
+- safe to send without overstating certainty

.opencode/commands/sync-context.md

@@ -0,0 +1,42 @@
+---
+description: Update workspace memory from new facts, corrections, or Mattermost notes
+---
+
+Use this command when new information should become part of the persistent workspace context.
+
+Read:
+
+@README.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/context/people/jeff.md
+@ai/state/current.md
+@knowledge/workspace-model.md
+@knowledge/communication-rules.md
+
+Today's existing log, if present:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+New information to incorporate:
+
+$ARGUMENTS
+
+Instructions:
+
+- Decide whether the new information belongs in:
+  - today's log
+  - `ai/state/current.md`
+  - `ai/context/project.md`
+  - `ai/context/people/jeff.md`
+  - `ai/context/decisions/`
+- Update the appropriate files directly
+- If an existing statement became stale, replace or refine it
+- Do not invent missing facts
+- Keep uncertain information in the daily log instead of promoting it to stable context
+
+After editing, respond with:
+
+1. Updated files
+2. What changed in the persistent context
+3. Any uncertainty that remains

.opencode/commands/translate.md

@@ -0,0 +1,24 @@
+---
+description: Alias for Mattermost-ready translation and polishing
+---
+
+Translate and tighten the following rough notes into concise Mattermost-ready English:
+
+$ARGUMENTS
+
+Read:
+
+@prompts/mattermost-translation.md
+@ai/AGENTS.md
+@ai/context/project.md
+@ai/context/people/jeff.md
+@knowledge/communication-rules.md
+
+If relevant, use today's log for context:
+
+!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+
+Return:
+
+1. Clean message
+2. Short assumptions note

.opencode/plugins/fidelity-compaction.js

@@ -0,0 +1,65 @@
+import { readdir, readFile } from "node:fs/promises"
+import path from "node:path"
+
+async function safeRead(filePath) {
+  try {
+    return await readFile(filePath, "utf8")
+  } catch {
+    return null
+  }
+}
+
+export const FidelityCompaction = async ({ directory }) => {
+  return {
+    "experimental.session.compacting": async (_input, output) => {
+      const baseFiles = [
+        "README.md",
+        "ai/context/project.md",
+        "ai/context/people/jeff.md",
+        "ai/state/current.md",
+        "ai/context/decisions/rest-vs-graphql.md",
+        "ai/context/decisions/discourse-handling.md",
+        "knowledge/workspace-model.md",
+        "knowledge/communication-rules.md",
+      ]
+
+      const sections = []
+
+      for (const relPath of baseFiles) {
+        const content = await safeRead(path.join(directory, relPath))
+        if (content) {
+          sections.push(`### ${relPath}\n${content.trim()}`)
+        }
+      }
+
+      try {
+        const logsDir = path.join(directory, "ai/logs")
+        const logs = (await readdir(logsDir))
+          .filter((name) => name.endsWith(".md"))
+          .sort()
+          .slice(-2)
+
+        for (const logName of logs) {
+          const content = await safeRead(path.join(logsDir, logName))
+          if (content) {
+            sections.push(`### ai/logs/${logName}\n${content.trim()}`)
+          }
+        }
+      } catch {
+        // No logs available yet.
+      }
+
+      if (sections.length > 0) {
+        output.context.push(
+          [
+            "## Fidelity Workspace Persistent Context",
+            "Preserve this operational memory across compaction.",
+            "If later messages introduced corrections or durable facts, prefer the corrected view over stale summaries.",
+            "",
+            sections.join("\n\n"),
+          ].join("\n"),
+        )
+      }
+    },
+  }
+}

AGENTS.md

@@ -0,0 +1,41 @@
+# 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 Jeff in natural US English
+
+## Always-Loaded Context
+
+The detailed operating rules live in:
+
+- `ai/AGENTS.md`
+- `ai/context/project.md`
+- `ai/context/people/jeff.md`
+- `ai/state/current.md`
+- `knowledge/workspace-model.md`
+- `knowledge/communication-rules.md`
+
+These are also loaded through `opencode.json`.
+
+## Required Behavior
+
+- Assume the workspace may contain stale context until checked.
+- Before answering questions that depend on current work state, inspect `ai/state/current.md` and the latest relevant log under `ai/logs/`.
+- If the user provides durable new facts, update the appropriate context files instead of leaving the new information only in chat history.
+- 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.
+
+## 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

README.md

@@ -1,162 +1,164 @@
 # Fidelity AI Workspace
 
-Repositorio diseñado para centralizar contexto, memoria operativa y generación de contenido asistido por IA para el trabajo diario en proyectos de ingeniería.
+AI-native companion workspace for daily iOS engineering on Fidelity.
 
-Este proyecto no almacena código de producto. Su objetivo es organizar conocimiento, decisiones y comunicación para reutilizarlos de forma eficiente con herramientas de IA.
+This repository is not the product codebase. It is the operational context layer used from this machine to keep project state current, capture communication from Mattermost, prepare standups, and draft clear updates for Jeff in polished US English.
 
 ---
 
-## Objetivo
+## Purpose
 
-- Centralizar TODO el contexto de un único proyecto activo
-- Mantener trazabilidad de decisiones, tickets y comunicación
-- Reducir fricción al generar standups, updates y PRs
-- Reutilizar conocimiento en prompts de IA
-- Capturar aprendizaje continuo (feedback, errores, soluciones)
-- Tener una fuente de verdad viva del proyecto
+- Keep Fidelity context current outside the main development machine
+- Turn fragmented daily work into reusable AI-ready context
+- Support standups, manager updates, Jira notes, and debugging summaries
+- Improve communication quality without losing technical accuracy
 
 ---
 
-## Estructura del proyecto
+## Operating Model
 
-```
-memory/
-  project.md        Contexto principal del proyecto (estado, objetivos, tickets activos)
-  logs/             Registro diario de trabajo
-  people/           Stakeholders relevantes (manager, backend, etc)
-  decisions/        Decisiones técnicas y de producto
+You work on Fidelity from a different machine.
 
-prompts/
-  Templates reutilizables (standup, manager updates, PRs)
+This workspace is used to:
 
-scripts/
-  Automatización (generación de contexto, mensajes, etc)
+- record what happened during implementation and debugging
+- sync relevant communication from Mattermost
+- preserve current project context between sessions
+- draft messages for Jeff with the right tone and scope
+- translate rough notes into concise native-sounding English
 
-workflows/
-  Integraciones con herramientas externas (nexus, opencode)
+Core principle:
 
-README.md
-```
+Context must be updated before asking AI to write.
 
 ---
 
-## Flujo de trabajo diario
+## Project Scope
 
-### Inicio del día
+Fidelity iOS ecosystem:
 
-1. Revisar estado del proyecto en `memory/project.md`
-2. Revisar último log en `memory/logs/`
-3. Generar contexto actualizado del día
+- Fid4
+- XFlowSDK
+- FTFrameworks
+- REST migration replacing GraphQL over time
+- Discourse and AO issues that require careful classification
 
 ---
 
-### Durante el día
+## Structure
 
-Registrar avances en:
+### /ai
 
-```
-memory/logs/YYYY-MM-DD.md
-```
+Runtime context for AI support.
 
-Formato sugerido:
+- `AGENTS.md` -> behavior rules for AI agents
+- `context/` -> stable knowledge about Fidelity and team communication
+- `state/` -> current focus, active issues, and communication needs
+- `logs/` -> daily work record
 
-```
-## Trabajo realizado
-- ...
+### /prompts
 
-## Hallazgos
-- ...
+Reusable prompts for:
 
-## Bloqueos
-- ...
-```
+- standups
+- Mattermost updates
+- manager communication
+- issue clarification
+
+### /workflows
+
+Repeatable working guides for:
+
+- daily context sync
+- flow debugging
+- external issue analysis
+
+### /knowledge
+
+Reference material for:
+
+- XFlow behavior
+- communication rules
+- Fidelity-specific debugging heuristics
+
+### /scripts
+
+Helpers for future automation around context generation and communication drafting.
 
 ---
 
-### Fin del día
+## Daily Usage
 
-Actualizar log con:
+### Start of day
 
-- Qué se hizo
-- Qué se aprendió
-- Qué quedó pendiente
+Read:
+
+- `ai/state/current.md`
+- `ai/context/project.md`
+- `ai/context/people/jeff.md`
+- latest file under `ai/logs/`
+
+### During the day
+
+Capture:
+
+- implementation progress from the main development machine
+- Mattermost conversations that change scope or priorities
+- debugging findings
+- open questions, blockers, and follow-ups
+
+Write updates in:
+
+- `ai/logs/YYYY-MM-DD.md`
+
+### Before sending a message
+
+Confirm:
+
+- context
+- current observation
+- requested or implied action
+- whether the issue is external behavior or regression
+- whether the flow is authenticated or non-authenticated
+
+### End of day
+
+Update:
+
+- today log
+- current state
+- next communication needs for Jeff
 
 ---
 
-## Uso con IA
+## Expected Output
 
-Este repositorio actúa como capa de contexto para herramientas como ChatGPT, Claude u otros modelos.
+This workspace should help produce:
 
-Ejemplo:
-
-```
-Context:
-- memory/project.md
-- memory/logs/2026-04-09.md
-- memory/people/manager.md
-
-Task:
-- Generar standup
-- Mejorar mensaje para manager
-- Crear descripción de PR
-```
+- high-signal standups
+- clearer Mattermost updates
+- concise supervisor communication
+- better issue framing
+- more reliable AI-generated English
 
 ---
 
-## Prompts disponibles
+## OpenCode Entry Point
 
-Ubicados en `prompts/`
+This workspace is designed to work well with the OpenCode VS Code extension.
 
-Ejemplos:
+Recommended usage:
 
-- standup.md
-- manager-update.md
-- pr-description.md
+1. Open this repository as its own VS Code workspace.
+2. Start OpenCode from the integrated terminal at the repository root.
+3. Begin each session with `/fidelity-context`.
+4. As new information appears during the day, update context before asking for drafting help.
 
----
+Project commands live under `.opencode/commands/` and are intended to:
 
-## Scripts (planeado)
+- load the baseline Fidelity context
+- draft standups
+- draft Jeff updates
+- convert rough notes into daily log updates
 
-Ejemplos de comandos:
-
-```
-generate-context --project apple-pay --days 1
-generate-standup
-generate-message --manager
-```
-
----
-
-## Buenas prácticas
-
-- Mantener `project.md` siempre actualizado
-- Registrar avances diarios en logs
-- Documentar decisiones importantes
-- Capturar feedback del manager y stakeholders
-- Escribir pensando en reutilización para IA
-- Evitar duplicar contexto en múltiples archivos
-
----
-
-## Herramientas
-
-- VSCode como entorno principal
-- Basic Memory como base conceptual (estructura en Markdown)
-- Nexus Workflow Studio para automatización (opcional)
-- opencode para ejecución de workflows y agentes (opcional)
-
----
-
-## Roadmap
-
-- [ ] Scripts para generación automática de contexto
-- [ ] Integración con Mattermost
-- [ ] Automatización de standups
-- [ ] Sistema de tagging por proyecto
-- [ ] Búsqueda semántica
-
----
-
-## Notas
-
-Este workspace está diseñado para trabajar sobre un único proyecto activo. Si se inicia un nuevo proyecto, se recomienda crear un nuevo workspace o reiniciar la estructura para evitar mezclar contextos.
+This keeps AI output tied to the latest workspace state instead of relying on chat memory alone.

ai/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+## Role
+
+Senior iOS engineer supporting Fidelity from a companion AI workspace.
+
+This workspace is used to maintain context, organize communication, and draft accurate updates while the main implementation work happens on a different machine.
+
+---
+
+## Primary Responsibilities
+
+- Keep project context current
+- Convert Mattermost communication into structured notes
+- Draft standups and manager updates
+- Improve technical messages before sending them to Jeff
+- Translate rough notes into concise US English without changing meaning
+
+---
+
+## Fidelity Context
+
+- REST migration is replacing GraphQL over time
+- REST is behind a feature flag
+- GraphQL remains fallback
+- XFlow is backend-driven
+- Discourse and AO issues are often incomplete or ambiguous
+
+---
+
+## Communication Style
+
+Always structure technical updates as:
+
+1. Context
+2. Observation
+3. Action
+
+When drafting messages for Jeff:
+
+- be concise
+- be specific
+- avoid vague comparisons
+- make status and scope explicit
+
+---
+
+## Rules
+
+- Do not imply code changes were made from this workspace unless explicitly stated
+- Treat this repository as a context and communication layer, not the product codebase
+- Always clarify authenticated vs non-authenticated behavior
+- Do not assume REST is default
+- Separate external issues from regressions
+- State reproducibility clearly
+- If the user provides rough Spanish notes, translate them into natural US English
+- Preserve technical meaning when polishing communication
+
+---
+
+## Context Maintenance
+
+- 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/`
+- 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:
+  - `ai/state/current.md` for current focus or active concerns
+  - `ai/context/project.md` for durable project knowledge
+  - `ai/context/people/jeff.md` for communication preferences
+  - `ai/context/decisions/*.md` for confirmed decisions
+- Prefer updating stale context over leaving conflicting statements in different files
+- If context is still uncertain, record it in the daily log rather than promoting it to a stable context file
+
+---
+
+## Default Turn Behavior
+
+For day-to-day prompts in this workspace:
+
+1. Verify the latest relevant context.
+2. Decide whether the prompt introduces new durable information.
+3. Update the workspace when needed.
+4. Then answer using the refreshed context.
+
+---
+
+## Output
+
+Outputs should be:
+
+- clear
+- concise
+- actionable
+- manager-ready

ai/context/decisions/discourse-handling.md

@@ -0,0 +1,38 @@
+# Discourse Issues Handling
+
+## Context
+
+External reports from AO testing or Discourse may:
+
+- already exist in main
+- be partially reproducible
+- depend on authentication
+- reflect backend behavior rather than a new regression
+
+---
+
+## Decision
+
+Treat incoming reports as external issues until scope is confirmed.
+
+---
+
+## Validation Rules
+
+Always confirm:
+
+- reproducibility
+- environment
+- auth state
+- entry point
+- whether the issue exists in main
+
+---
+
+## Communication Rule
+
+Do not say a report is a regression until comparison has been validated.
+
+Preferred framing:
+
+"Investigating external report. Scope, auth state, and reproducibility still being confirmed."

ai/context/decisions/rest-vs-graphql.md

@@ -0,0 +1,30 @@
+# REST vs GraphQL
+
+## Decision
+
+Deprecate GraphQL and migrate to REST progressively.
+
+---
+
+## Constraints
+
+- REST is behind a feature flag
+- GraphQL remains fallback
+- Behavior parity matters during migration
+
+---
+
+## Communication Rule
+
+When reporting findings:
+
+- state whether REST was confirmed enabled
+- avoid implying REST is the default path
+- call out when behavior may still come from GraphQL fallback
+
+---
+
+## Follow-up
+
+- Remove Apollo when migration is safe
+- Retire GraphQL-specific tests only after parity is confirmed

ai/context/people/jeff.md

@@ -0,0 +1,40 @@
+# Jeff
+
+## Role
+
+Direct supervisor.
+
+---
+
+## Communication Requirements
+
+- Native US English
+- Prefers clear, concise updates
+- Needs accurate scope, not vague reassurance
+- Should be informed of meaningful progress from this machine through Mattermost
+
+---
+
+## What Good Updates Include
+
+1. Context
+2. Observation
+3. Action
+
+Good updates usually clarify:
+
+- what issue or task is being discussed
+- whether the behavior is reproducible
+- whether auth state matters
+- whether this looks like an external issue or a regression
+- what the next step is
+
+---
+
+## AI Usage
+
+AI should help:
+
+- translate rough Spanish notes into natural US English
+- tighten wording before sending
+- remove ambiguity without changing technical meaning

ai/context/project.md

@@ -0,0 +1,79 @@
+# Project Context - Fidelity
+
+## Overview
+
+This workspace supports daily iOS engineering work for Fidelity.
+
+The product work happens outside this repository, usually from another machine. This repository exists to preserve context, track communication, and help AI generate accurate output for standups, Mattermost messages, Jira notes, and supervisor updates.
+
+---
+
+## Fidelity Ecosystem
+
+- Fid4 is the main consumer iOS app
+- XFlowSDK powers backend-driven UI flows
+- XFlowViewMaker is an adapter layer under evaluation for removal
+- FTFrameworks contains feature modules such as FTAccountOpen and FTTransfer
+
+---
+
+## Current Priorities
+
+### REST migration
+
+- REST is behind a feature flag
+- GraphQL is still the default fallback
+- REST should never be assumed active unless confirmed
+- Migration must preserve behavior while Apollo is deprecated safely
+
+### Discourse and AO issues
+
+- External reports are often incomplete
+- Many reported issues are not confirmed regressions
+- Some issues reproduce only with authenticated users
+
+### Flow debugging
+
+- XFlow behavior changes based on backend configuration
+- Entry point affects what the user sees
+- Authentication state affects reproducibility
+
+### Testing complexity
+
+- Around 15 entry points have been identified at code level
+- Not all entry points are reachable from visible UI
+- Validation often requires exploratory testing
+
+---
+
+## How This Workspace Is Used
+
+This machine is used to:
+
+- maintain current project context
+- record findings from work performed elsewhere
+- capture Mattermost communication that changes understanding
+- prepare polished updates for Jeff
+- generate standups with better context coverage
+
+This means logs must capture both technical findings and communication context.
+
+---
+
+## Communication Expectations
+
+All important updates should clarify:
+
+- whether the flow is authenticated or non-authenticated
+- whether the issue is reproducible
+- whether the report is external behavior or regression
+- whether behavior is present in main
+- what action is needed next
+
+Avoid phrases that hide scope, such as:
+
+- "same behavior"
+- "looks fixed"
+- "working as expected"
+
+Use explicit framing instead.

ai/logs/2026-04-08.md

@@ -0,0 +1,28 @@
+# 2026-04-08
+
+## Work Done
+
+- Investigated a Youth account flow issue reported externally
+- Compared the observed behavior against prior flow behavior
+- Captured notes to explain the issue clearly before sharing updates
+
+---
+
+## Findings
+
+- Reproduction required an authenticated user
+- Behavior appeared consistent with previously observed flow behavior
+- The report did not yet prove a regression
+
+---
+
+## Communication
+
+- Prepared a clearer explanation for follow-up through Mattermost
+- Framed the issue as an external report pending scope confirmation
+
+---
+
+## Next Step
+
+- Confirm whether any additional action is needed before closing the issue

ai/logs/2026-04-09.md

@@ -0,0 +1,28 @@
+# 2026-04-09
+
+## Work Done
+
+- Refined manager-facing communication about a reported behavior difference
+- Reframed ambiguous language before documenting the outcome in Jira
+- Updated context to reflect auth-dependent behavior
+
+---
+
+## Findings
+
+- The reported behavior depended on authenticated context
+- The original external report was incomplete
+- The comparison needed more precise wording to avoid implying regression
+
+---
+
+## Communication
+
+- Prepared clearer wording for Jeff
+- Focused on context, observation, and action instead of vague comparison language
+
+---
+
+## Next Step
+
+- Keep using explicit issue framing for future Mattermost and Jira updates

ai/state/current.md

@@ -0,0 +1,34 @@
+# Current Work
+
+## Focus
+
+- Keep Fidelity context current from daily work performed on another machine
+- Track REST migration findings
+- Debug Discourse and AO issues
+- Prepare better updates for Jeff through Mattermost
+
+---
+
+## Active Concerns
+
+- Authenticated vs non-authenticated behavior
+- Reproducibility across entry points
+- Backend-driven inconsistencies in XFlow
+- Distinguishing external issues from true regressions
+- Preserving accurate context when summarizing work from another machine
+
+---
+
+## Communication Priorities
+
+- Standups should reflect the latest technical state, not generic progress
+- Manager updates should be short, precise, and natural in English
+- Mattermost messages should make scope and next action explicit
+
+---
+
+## Notes
+
+- REST remains behind a feature flag
+- Validate against main before calling something a regression
+- This workspace is the context source for communication, not the source of product code changes

knowledge/.gitkeep

@@ -0,0 +1 @@
+

knowledge/communication-rules.md

@@ -0,0 +1,26 @@
+# Communication Rules
+
+## Purpose
+
+These rules keep standups, Jira notes, and Mattermost messages aligned with the actual state of the work.
+
+---
+
+## Rules
+
+- Prefer explicit scope over short vague statements
+- Always mention auth state when it changes reproducibility
+- Separate external report from regression
+- Say whether behavior was confirmed in main when that comparison exists
+- End with the next action when writing status updates
+
+---
+
+## Avoid
+
+- "same behavior"
+- "looks good"
+- "seems fixed"
+- "working now"
+
+Use concrete statements instead.

knowledge/workspace-model.md

@@ -0,0 +1,23 @@
+# Workspace Model
+
+## Purpose
+
+This repository is a support workspace, not the implementation repository.
+
+---
+
+## What belongs here
+
+- daily logs
+- communication context
+- manager update drafts
+- stable project knowledge
+- debugging summaries
+
+---
+
+## What does not belong here
+
+- product source code
+- assumptions about code changes not yet verified
+- statements that imply work was executed from this machine unless explicitly true

opencode.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "fidelity",
+  "share": "manual",
+  "instructions": [
+    "./README.md",
+    "./ai/context/project.md",
+    "./ai/context/people/jeff.md",
+    "./ai/state/current.md",
+    "./ai/context/decisions/rest-vs-graphql.md",
+    "./ai/context/decisions/discourse-handling.md",
+    "./ai/AGENTS.md",
+    "./knowledge/workspace-model.md",
+    "./knowledge/communication-rules.md"
+  ]
+}

prompts/.gitkeep

@@ -0,0 +1 @@
+

prompts/manager-update.md

@@ -0,0 +1,14 @@
+# Manager Update Prompt
+
+Use the current state, today's log, and `ai/context/people/jeff.md`.
+
+Draft a Mattermost update for Jeff in concise US English.
+
+Requirements:
+
+- Structure around Context, Observation, and Action
+- Make scope explicit
+- Clarify whether the issue is external behavior or regression
+- Mention auth state when relevant
+- Preserve the original technical meaning
+- Keep the message direct and short

prompts/mattermost-translation.md

@@ -0,0 +1,16 @@
+# Mattermost Translation Prompt
+
+Translate rough engineering notes into natural US English for Mattermost.
+
+Requirements:
+
+- Preserve exact technical meaning
+- Remove ambiguity
+- Prefer concise wording
+- Keep the tone professional and direct
+- If the draft lacks context, infer only from workspace files and do not invent facts
+
+Output:
+
+1. Clean message
+2. Short note listing any assumptions made

prompts/standup.md

@@ -0,0 +1,25 @@
+# Standup Prompt
+
+Use the latest files in `ai/state/current.md`, `ai/context/project.md`, `ai/context/people/jeff.md`, and today's log.
+
+Generate a standup update for an iOS engineer working on Fidelity.
+
+Requirements:
+
+- Use the most recent context only
+- Be specific about what was worked on
+- Mention debugging findings only if they materially changed understanding
+- Clarify auth-dependent behavior when relevant
+- Avoid vague phrases and generic progress language
+- Keep it concise and ready to send
+
+Format:
+
+Yesterday:
+- ...
+
+Today:
+- ...
+
+Blockers:
+- ...

scripts/.gitkeep

@@ -0,0 +1 @@
+

scripts/README.md

@@ -0,0 +1,10 @@
+# Scripts
+
+This directory is reserved for future helpers that automate:
+
+- context aggregation
+- standup generation
+- manager update drafting
+- Mattermost-ready message formatting
+
+No automation has been implemented yet. The current workflow is document-driven.

workflows/daily-context-sync.md

@@ -0,0 +1,16 @@
+# Daily Context Sync
+
+## Goal
+
+Keep this workspace aligned with work happening on another machine so AI output stays current and useful.
+
+---
+
+## Steps
+
+1. Capture the main tasks worked on during the day.
+2. Record key debugging findings and open questions.
+3. Copy relevant Mattermost communication into the daily log as summarized notes.
+4. Update `ai/state/current.md` if priorities or concerns changed.
+5. Add any stable learning to `ai/context/` or `knowledge/`.
+6. Before asking AI for a standup or manager update, confirm the log reflects the latest state.

workflows/debug-flow.md

@@ -0,0 +1,21 @@
+# Debugging Flow Strategy
+
+## Goal
+
+Turn incomplete reports into clear, reproducible debugging context that can be shared accurately.
+
+---
+
+## Steps
+
+1. Identify the entry point.
+2. Confirm whether the user is authenticated or non-authenticated.
+3. Capture the reported behavior exactly as described.
+4. Reproduce the issue if possible.
+5. Compare expected versus actual behavior.
+6. Check whether the same behavior exists in main.
+7. Classify the issue as:
+   - external report
+   - existing behavior
+   - regression
+8. Write the result using Context, Observation, and Action.

workflows/manager-update.md

@@ -0,0 +1,26 @@
+# Manager Update Workflow
+
+## Goal
+
+Prepare a concise, accurate Mattermost update for Jeff.
+
+---
+
+## Checklist
+
+1. Confirm the task or issue being discussed.
+2. State whether the behavior depends on authentication.
+3. Clarify whether this is an external issue or a confirmed regression.
+4. Summarize the current observation in plain language.
+5. End with the next action or decision point.
+
+---
+
+## Quality Bar
+
+The final message should:
+
+- sound natural in US English
+- avoid vague comparisons
+- preserve technical accuracy
+- be short enough for Mattermost

workflows/opencode-entry.md

@@ -0,0 +1,35 @@
+# OpenCode Entry Workflow
+
+## Goal
+
+Use OpenCode as the daily AI entry point for this workspace without losing project context.
+
+---
+
+## Setup
+
+1. Open this repository as its own VS Code workspace.
+2. Run `opencode` from the integrated terminal at the repository root.
+3. Use the `fidelity` primary agent when available.
+4. Let project-level config load from `AGENTS.md`, `opencode.json`, `.opencode/commands/`, and `.opencode/plugins/`.
+
+---
+
+## Recommended Daily Sequence
+
+1. Run `/fidelity-context` at the start of the day.
+2. When new work happens on the main development machine, run `/sync-context ...` or `/log-note ...`.
+3. When you need a supervisor update, run `/jeff-update ...`.
+4. When you need polished English for Mattermost, run `/translate ...`.
+5. When you need a standup, run `/standup`.
+
+---
+
+## Why This Works
+
+- Project instructions load automatically from `opencode.json`.
+- Root rules also load automatically from `AGENTS.md`.
+- The main context command reads the stable workspace files plus today's log.
+- Daily updates go back into the workspace, so later prompts inherit better context.
+- The local compaction plugin helps preserve the most important workspace context during long sessions.
+- This reduces reliance on fragile session memory.