This repository is not the product codebase. It is an operational context layer used to keep project state current, capture communication evidence, prepare standups, draft clear stakeholder updates, and generate self-contained prompts for another AI that has access to the implementation codebase.

The reusable logic lives in core/. Fidelity-specific context lives in the active profile and existing ai/context/ memory.

Purpose

Provide a reusable file-based AI workspace pattern
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
Generate high-quality prompts for GitHub Copilot or another AI on the Fidelity development machine
Improve communication quality without losing technical accuracy

Operating Model

You work on Fidelity from a different machine.

This workspace is used to:

record what happened during implementation and debugging
sync relevant communication from Mattermost
preserve current project context between sessions
draft messages for the current manager or stakeholder with the right tone and scope
translate rough notes into concise native-sounding English
generate self-contained prompts for another AI that does have access to the product codebase

Core principle:

Context must be updated before asking AI to write.

Reusable principle:

Integrations extract evidence. The agent promotes memory.

Reusable Architecture

/core

Project-independent workspace logic.

README.md -> reusable operating model
memory/operational-memory.md -> memory classes, promotion rules, correction rules, self-maintenance rules
integrations/communication-model.md -> live communication and historical archive connector contract
profiles/create-project-profile.md -> checklist for adapting the workspace to another project

/profiles

Project-specific configuration.

profiles/fidelity/ -> active Fidelity implementation profile
profiles/example/ -> non-sensitive example profile for new projects

Profiles declare project assumptions, communication sources, work-item system, stakeholders, enabled commands, and enabled skills.

Project Scope

Fidelity iOS ecosystem:

Fid4
XFlowSDK
FTFrameworks
REST migration replacing GraphQL over time
Discourse and AO issues that require careful classification

Structure

/ai

Runtime context for AI support.

AGENTS.md -> behavior rules for AI agents
context/ -> stable knowledge organized by systems, workstreams, process, people, and decisions
context/ios/ -> Swift and iOS answer policy for current best practices and Fidelity-specific constraints
work-items/ -> one file per active Jira-linked unit of work
state/ -> current focus, active issues, and communication needs
logs/ -> daily work record

/prompts

Reusable prompts for:

standups
Mattermost updates
manager communication
issue clarification

/workflows

Repeatable working guides for:

daily context sync
flow debugging
external issue analysis

/knowledge

Reference material for:

reusable memory rules
workspace model
XFlow behavior
communication rules
Fidelity-specific debugging heuristics
Obsidian vault navigation

/scripts

Helpers for future automation around context generation and communication drafting.

/.obsidian

Optional Obsidian vault configuration.

Open the repository root as the vault. Obsidian should navigate and edit the same Markdown files used by OpenCode; it should not duplicate memory into a separate store.

Portable vault configuration can be versioned, while local layout and plugin runtime files are ignored.

Daily Usage

Start of day

Read:

ai/context/index.md
ai/work-items/index.md
ai/state/current.md
ai/context/project.md
ai/context/people/manager.md
ai/context/people/index.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 the current manager or stakeholder

Expected Output

This workspace should help produce:

high-signal standups
clearer Mattermost updates
concise supervisor communication
better issue framing
more reliable AI-generated English

OpenCode Entry Point

This workspace is designed to work well with the OpenCode VS Code extension.

Recommended usage:

Open this repository as its own VS Code workspace.
Start OpenCode from the integrated terminal at the repository root.
Begin each session with /workspace-context or the Fidelity alias /fidelity-context.
As new information appears during the day, update context before asking for drafting help.

Project commands live under .opencode/commands/ and are intended to:

load the reusable core plus active project profile
sync live communication context into the workspace inbox
draft standups
draft manager updates
draft prompts for another AI on the implementation machine
force-refresh and inspect latest communication messages
convert rough notes into daily log updates

This keeps AI output tied to the latest workspace state instead of relying on chat memory alone.

Generic Commands

/workspace-context -> load core plus active profile
/communication-sync -> sync live communication evidence and promote high-confidence memory
/archive-import -> import historical archive evidence
/ai-prompt -> generate a self-contained prompt for another AI
/standup -> generate a work-item-aware daily standup
/manager-update -> draft stakeholder-ready status
/translate -> rewrite rough notes into professional English
/sync-context -> incorporate new facts or corrections into memory

Compatibility aliases remain available for the Fidelity profile:

/fidelity-context
/mattermost-sync
/slack-import
/copilot-prompt
/swift-help

Communication Memory Flow

This workspace supports a live-memory pattern for communication sources such as Mattermost.

Recommended setup:

Use the workspace-local script at scripts/mattermost/sync.sh, or override it with AIW_MATTERMOST_SYNC_CMD.
Let OpenCode run with the project plugins enabled.
The Mattermost inbox plugin will periodically refresh ai/inbox/mattermost-latest.md.
Promote durable facts from the inbox into ai/logs/, ai/state/, and ai/context/.

Use /communication-sync or /mattermost-sync when you want to force a refresh manually.

Generic environment variables:

AIW_PROJECT_PROFILE
AIW_CHANNEL_PREFIX
AIW_MATTERMOST_SYNC_CMD
AIW_MATTERMOST_SYNC_INTERVAL_MINUTES
AIW_SLACK_EXPORT_PATH

The older FIDELITY_* variables remain supported for compatibility with this project profile.

Obsidian Vault

This repository can be opened directly as an Obsidian vault.

Recommended entry point:

knowledge/obsidian-vault.md
knowledge/onboarding.md for new members
knowledge/glossary.md for terminology
knowledge/obsidian-usage.md for navigation rules

Use Obsidian for:

visual navigation
graph/backlink review
manual review of work items, people, decisions, and logs
lightweight editing of the same Markdown memory files

Do not use Obsidian as a second memory database. The source of truth remains the versioned Markdown files in this repository.

Ignored Obsidian runtime files include workspace layout, plugin cache, snippets, and local plugin installs.

Creating Another Project

Copy profiles/example/ to profiles/<project>/.
Fill in profiles/<project>/profile.md.
Set AIW_PROJECT_PROFILE=<project>.
Configure any communication connector with AIW_* variables.
Keep project-specific context under ai/context/, not under core/.
Use /workspace-context to load the core plus active profile.

See core/profiles/create-project-profile.md for the full checklist.