From ae9e69bd4bf09dd3d30dc732d98db5cdd34d9a9c Mon Sep 17 00:00:00 2001 From: "david.delagneau" Date: Fri, 10 Apr 2026 08:57:00 -0600 Subject: [PATCH] feat: Organize context files and enhance documentation for clarity and structure --- .opencode/agents/fidelity.md | 5 +- .opencode/commands/fidelity-context.md | 5 ++ .opencode/commands/log-note.md | 4 + .opencode/commands/manager-update.md | 4 +- .opencode/commands/promote-project-context.md | 7 ++ .opencode/commands/slack-import.md | 4 + .opencode/commands/standup.md | 5 +- .opencode/commands/story-draft.md | 8 +- .opencode/commands/sync-context.md | 7 ++ .opencode/commands/translate.md | 2 + .opencode/plugins/fidelity-compaction.js | 4 + AGENTS.md | 5 ++ README.md | 3 +- ai/AGENTS.md | 2 + ai/context/index.md | 60 +++++++++++++ ai/context/process/communication.md | 35 ++++++++ ai/context/process/context-maintenance.md | 33 +++++++ ai/context/process/index.md | 12 +++ ai/context/process/jira-story-rules.md | 30 +++++++ ai/context/project.md | 88 ++++++------------- ai/context/systems/fid4.md | 30 +++++++ ai/context/systems/ftframeworks.md | 32 +++++++ ai/context/systems/index.md | 23 +++++ ai/context/systems/xflowsdk.md | 39 ++++++++ ai/context/systems/xflowviewmaker.md | 29 ++++++ ai/context/workstreams/ao-discourse.md | 33 +++++++ .../workstreams/consumer-integration.md | 36 ++++++++ ai/context/workstreams/index.md | 26 ++++++ ai/context/workstreams/rest-migration.md | 32 +++++++ ai/context/workstreams/xflow-debugging.md | 37 ++++++++ .../workstreams/xflow-swiftui-migration.md | 35 ++++++++ ai/logs/2026-04-10.md | 1 + ai/state/current.md | 1 + ai/state/work-items.md | 4 +- opencode.json | 5 ++ prompts/manager-update.md | 2 +- prompts/standup.md | 2 +- workflows/opencode-entry.md | 1 + 38 files changed, 620 insertions(+), 71 deletions(-) create mode 100644 ai/context/index.md create mode 100644 ai/context/process/communication.md create mode 100644 ai/context/process/context-maintenance.md create mode 100644 ai/context/process/index.md create mode 100644 ai/context/process/jira-story-rules.md create mode 100644 ai/context/systems/fid4.md create mode 100644 ai/context/systems/ftframeworks.md create mode 100644 ai/context/systems/index.md create mode 100644 ai/context/systems/xflowsdk.md create mode 100644 ai/context/systems/xflowviewmaker.md create mode 100644 ai/context/workstreams/ao-discourse.md create mode 100644 ai/context/workstreams/consumer-integration.md create mode 100644 ai/context/workstreams/index.md create mode 100644 ai/context/workstreams/rest-migration.md create mode 100644 ai/context/workstreams/xflow-debugging.md create mode 100644 ai/context/workstreams/xflow-swiftui-migration.md diff --git a/.opencode/agents/fidelity.md b/.opencode/agents/fidelity.md index 3d16933..415b0a1 100644 --- a/.opencode/agents/fidelity.md +++ b/.opencode/agents/fidelity.md @@ -19,7 +19,10 @@ Behavior rules: - daily facts go to `ai/logs/YYYY-MM-DD.md` - current priorities go to `ai/state/current.md` - active Jira-linked work goes to `ai/state/work-items.md` - - durable project knowledge goes to `ai/context/project.md` + - durable project knowledge overview goes to `ai/context/project.md` + - system-specific durable knowledge goes to `ai/context/systems/` + - workstream-specific durable knowledge goes to `ai/context/workstreams/` + - process-specific durable knowledge goes to `ai/context/process/` - confirmed team or manager communication preferences go to `ai/context/people/manager.md` - role-to-person mapping and recurring stakeholders go to `ai/context/people/` - confirmed decisions go to `ai/context/decisions/` diff --git a/.opencode/commands/fidelity-context.md b/.opencode/commands/fidelity-context.md index e26a091..d13ebf1 100644 --- a/.opencode/commands/fidelity-context.md +++ b/.opencode/commands/fidelity-context.md @@ -8,7 +8,12 @@ Use these files as the baseline context: @README.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/systems/index.md +@ai/context/workstreams/index.md +@ai/context/process/communication.md +@ai/context/process/jira-story-rules.md @ai/context/people/manager.md @ai/context/people/index.md @ai/state/current.md diff --git a/.opencode/commands/log-note.md b/.opencode/commands/log-note.md index daab017..ba030e2 100644 --- a/.opencode/commands/log-note.md +++ b/.opencode/commands/log-note.md @@ -8,7 +8,10 @@ Read: @README.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/workstreams/index.md +@ai/context/process/context-maintenance.md @ai/state/current.md @ai/state/work-items.md @knowledge/agent-memory-rules.md @@ -30,6 +33,7 @@ Instructions: - Keep the log concise but reusable for later standups and manager updates - If the notes are ambiguous, normalize them without inventing facts - If a note clearly corrects or sharpens existing current memory, update the corresponding canonical file as well +- If a note reveals durable system, workstream, process, or people context, update the relevant canonical file instead of only appending to the log - Prefer `sync-context` for broader memory updates; use this command for fast daily capture After editing, respond with: diff --git a/.opencode/commands/manager-update.md b/.opencode/commands/manager-update.md index 8d64239..66febef 100644 --- a/.opencode/commands/manager-update.md +++ b/.opencode/commands/manager-update.md @@ -8,9 +8,11 @@ Read: @prompts/manager-update.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/workstreams/index.md +@ai/context/process/communication.md @ai/context/people/manager.md -@ai/context/people/jeff-dewitte.md @ai/context/people/index.md @ai/state/current.md @ai/state/work-items.md diff --git a/.opencode/commands/promote-project-context.md b/.opencode/commands/promote-project-context.md index 3cb2c2d..352f4b1 100644 --- a/.opencode/commands/promote-project-context.md +++ b/.opencode/commands/promote-project-context.md @@ -7,7 +7,11 @@ Use this only when you want an explicit manual promotion pass. Read: @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/systems/index.md +@ai/context/workstreams/index.md +@ai/context/process/index.md @ai/state/current.md @ai/state/work-items.md @knowledge/workspace-model.md @@ -39,6 +43,9 @@ Instructions: - `ai/state/current.md` - `ai/state/work-items.md` - `ai/context/project.md` + - `ai/context/systems/*.md` + - `ai/context/workstreams/*.md` + - `ai/context/process/*.md` - `ai/context/decisions/*.md` - Prefer concrete project updates over broad summaries - If a fact is still ambiguous, do not promote it diff --git a/.opencode/commands/slack-import.md b/.opencode/commands/slack-import.md index 2d1be29..56fc6a8 100644 --- a/.opencode/commands/slack-import.md +++ b/.opencode/commands/slack-import.md @@ -23,7 +23,11 @@ First, run the importer: Read: @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/systems/index.md +@ai/context/workstreams/index.md +@ai/context/process/index.md @ai/context/people/index.md @ai/context/people/manager.md @ai/state/current.md diff --git a/.opencode/commands/standup.md b/.opencode/commands/standup.md index 2a611b0..1d4c124 100644 --- a/.opencode/commands/standup.md +++ b/.opencode/commands/standup.md @@ -12,9 +12,12 @@ Read: @prompts/standup.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/workstreams/index.md +@ai/context/process/communication.md +@ai/context/process/jira-story-rules.md @ai/context/people/manager.md -@ai/context/people/jeff-dewitte.md @ai/state/current.md @ai/state/work-items.md @knowledge/communication-rules.md diff --git a/.opencode/commands/story-draft.md b/.opencode/commands/story-draft.md index 5ec3355..4a813e6 100644 --- a/.opencode/commands/story-draft.md +++ b/.opencode/commands/story-draft.md @@ -10,7 +10,7 @@ This command should optimize for: - explicit scope - useful acceptance criteria - clear ownership framing -- natural US English that Jeff can reuse or forward without rewriting +- natural US English that the current manager or stakeholder can reuse or forward without rewriting Input notes or rough idea: @@ -20,9 +20,12 @@ Read: @prompts/story-draft.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/workstreams/index.md +@ai/context/process/communication.md +@ai/context/process/jira-story-rules.md @ai/context/people/manager.md -@ai/context/people/jeff-dewitte.md @ai/context/people/index.md @ai/state/current.md @ai/state/work-items.md @@ -50,6 +53,7 @@ Requirements: - Acceptance criteria should be testable and scoped to the proposed story - If the story looks too large or too ambiguous, say so explicitly and suggest spike framing instead - If useful, include a short note about dependencies, blockers, or coordination needed +- If the story touches consumer validation or release propagation, reflect that explicitly in the description or notes Return: diff --git a/.opencode/commands/sync-context.md b/.opencode/commands/sync-context.md index 49b1376..7a678e2 100644 --- a/.opencode/commands/sync-context.md +++ b/.opencode/commands/sync-context.md @@ -8,7 +8,11 @@ Read: @README.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/systems/index.md +@ai/context/workstreams/index.md +@ai/context/process/context-maintenance.md @ai/context/people/manager.md @ai/context/people/index.md @ai/state/current.md @@ -33,6 +37,9 @@ Instructions: - `ai/state/current.md` - `ai/state/work-items.md` - `ai/context/project.md` + - `ai/context/systems/` + - `ai/context/workstreams/` + - `ai/context/process/` - `ai/context/people/manager.md` - `ai/context/people/index.md` - `ai/context/people/*.md` diff --git a/.opencode/commands/translate.md b/.opencode/commands/translate.md index 12b5fd7..1d25420 100644 --- a/.opencode/commands/translate.md +++ b/.opencode/commands/translate.md @@ -15,7 +15,9 @@ Read: @prompts/mattermost-translation.md @ai/AGENTS.md +@ai/context/index.md @ai/context/project.md +@ai/context/process/communication.md @ai/context/people/manager.md @ai/context/people/index.md @knowledge/communication-rules.md diff --git a/.opencode/plugins/fidelity-compaction.js b/.opencode/plugins/fidelity-compaction.js index 007ce11..06b0376 100644 --- a/.opencode/plugins/fidelity-compaction.js +++ b/.opencode/plugins/fidelity-compaction.js @@ -14,7 +14,11 @@ export const FidelityCompaction = async ({ directory }) => { "experimental.session.compacting": async (_input, output) => { const baseFiles = [ "README.md", + "ai/context/index.md", "ai/context/project.md", + "ai/context/systems/index.md", + "ai/context/workstreams/index.md", + "ai/context/process/communication.md", "ai/context/people/manager.md", "ai/context/people/index.md", "ai/state/current.md", diff --git a/AGENTS.md b/AGENTS.md index 65d22a5..21d72b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,11 @@ OpenCode should treat this project as a persistent context layer used to: The detailed operating rules live in: - `ai/AGENTS.md` +- `ai/context/index.md` - `ai/context/project.md` +- `ai/context/systems/index.md` +- `ai/context/workstreams/index.md` +- `ai/context/process/communication.md` - `ai/context/people/manager.md` - `ai/context/people/index.md` - `ai/state/current.md` @@ -47,6 +51,7 @@ These are also loaded through `opencode.json`. - 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 `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` instead of overloading `ai/context/project.md`. ## Communication diff --git a/README.md b/README.md index fa15a2e..920a6f9 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ Fidelity iOS ecosystem: Runtime context for AI support. - `AGENTS.md` -> behavior rules for AI agents -- `context/` -> stable knowledge about Fidelity and team communication +- `context/` -> stable knowledge organized by systems, workstreams, process, people, and decisions - `state/` -> current focus, active issues, and communication needs - `logs/` -> daily work record @@ -93,6 +93,7 @@ Helpers for future automation around context generation and communication drafti Read: +- `ai/context/index.md` - `ai/state/current.md` - `ai/context/project.md` - `ai/context/people/manager.md` diff --git a/ai/AGENTS.md b/ai/AGENTS.md index 9b900eb..08b10d0 100644 --- a/ai/AGENTS.md +++ b/ai/AGENTS.md @@ -62,6 +62,7 @@ When drafting messages for a manager or stakeholder: - 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/` +- Before answering architecture, process, or historical questions, check the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` - If `ai/inbox/mattermost-latest.md` exists, check it before answering prompts about current status, standups, or supervisor communication - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands - If a Mattermost sync or other context-ingestion step fails, do not update `ai/logs/`, `ai/state/`, or stable context files based on that failure @@ -72,6 +73,7 @@ When drafting messages for a manager or stakeholder: - Promote to `ai/state/current.md` only when the fact changes the active work window - Maintain `ai/state/work-items.md` with explicit Jira IDs, approved titles, and currently relevant scope/status notes - Promote to `ai/context/project.md` only when the fact is durable beyond the current work window +- Use `ai/context/project.md` as the overview only; put system-specific, workstream-specific, and process-specific durable context in the corresponding subdirectory - Maintain `ai/context/people/` when repeated names, roles, or stakeholder relationships become useful for future sessions - Update existing memory when the new information is a correction, clarification, or refinement of something already stored - Prefer updating stable project context over appending generic operational summaries diff --git a/ai/context/index.md b/ai/context/index.md new file mode 100644 index 0000000..1ac3c7d --- /dev/null +++ b/ai/context/index.md @@ -0,0 +1,60 @@ +# Context Index + +## Goal + +Keep stable Fidelity context organized by domain so the agent can load the right information quickly. + +--- + +## Structure + +### `project.md` + +High-level overview of the workspace, current Fidelity scope, and where durable context lives. + +### `systems/` + +Stable context about core product components and how they relate: + +- [systems/fid4.md](./systems/fid4.md) +- [systems/xflowsdk.md](./systems/xflowsdk.md) +- [systems/xflowviewmaker.md](./systems/xflowviewmaker.md) +- [systems/ftframeworks.md](./systems/ftframeworks.md) + +### `workstreams/` + +Durable context about recurring streams of work and investigation: + +- [workstreams/rest-migration.md](./workstreams/rest-migration.md) +- [workstreams/ao-discourse.md](./workstreams/ao-discourse.md) +- [workstreams/xflow-debugging.md](./workstreams/xflow-debugging.md) +- [workstreams/xflow-swiftui-migration.md](./workstreams/xflow-swiftui-migration.md) +- [workstreams/consumer-integration.md](./workstreams/consumer-integration.md) + +### `process/` + +Rules and expectations for how work should be communicated and maintained: + +- [process/communication.md](./process/communication.md) +- [process/jira-story-rules.md](./process/jira-story-rules.md) +- [process/context-maintenance.md](./process/context-maintenance.md) + +### `people/` + +Named people, role mapping, and collaboration context: + +- [people/index.md](./people/index.md) +- [people/manager.md](./people/manager.md) + +### `decisions/` + +Confirmed technical or product decisions with ongoing impact. + +--- + +## Usage + +- Load `project.md` and this index first. +- Open `systems/` when the question is about architecture, ownership, or integration. +- Open `workstreams/` when the question is about current priorities, debugging themes, or historical project patterns. +- Open `process/` when drafting messages, standups, Jira notes, or deciding how to update memory. diff --git a/ai/context/process/communication.md b/ai/context/process/communication.md new file mode 100644 index 0000000..b9ca204 --- /dev/null +++ b/ai/context/process/communication.md @@ -0,0 +1,35 @@ +# Communication Rules + +## Goal + +Make technical communication precise enough for manager updates, Jira notes, standups, and cross-team messages. + +--- + +## Required Structure + +When the format fits, prefer: + +1. Context +2. Observation +3. Action + +--- + +## Fidelity-Specific Rules + +- Always clarify authenticated vs non-authenticated when behavior depends on it. +- Always separate external issues from regressions. +- Always state reproducibility and scope. +- Avoid vague phrasing such as: + - "same behavior" + - "looks fixed" + - "working as expected" + +--- + +## Historical Signals From Slack + +- Jeff repeatedly requested polished, explicit wording for PR descriptions, story descriptions, and cross-team messages. +- Historical Slack threads show that message quality changed how quickly stories were approved or understood. +- Explicit language mattered most when communicating root cause, ownership boundaries, or whether a report was a confirmed regression. diff --git a/ai/context/process/context-maintenance.md b/ai/context/process/context-maintenance.md new file mode 100644 index 0000000..e53e126 --- /dev/null +++ b/ai/context/process/context-maintenance.md @@ -0,0 +1,33 @@ +# Context Maintenance + +## Goal + +Keep this workspace useful as living memory instead of a pile of disconnected notes. + +--- + +## Stable Rules + +- Update canonical context when a durable fact changes. +- Prefer correcting stale context over appending contradictory notes. +- Use the smallest correct destination: + - `ai/logs/YYYY-MM-DD.md` for daily progress and evolving findings + - `ai/state/current.md` for near-term active work + - `ai/state/work-items.md` for Jira-linked active work + - `ai/context/` for durable project knowledge + - `ai/context/people/` for named person context + +--- + +## Ingestion Rules + +- Treat Mattermost, Slack history, and direct prompts as potential memory sources. +- Do not promote failed syncs or tooling errors as project facts. +- Promote repeated durable patterns from historical archives into stable context when confidence is high. +- Keep old status-only details archive-only unless they still change current understanding. + +--- + +## Curation Rule + +- If a new stable context file is added, keep `project.md` and `index.md` aligned so future sessions can discover it quickly. diff --git a/ai/context/process/index.md b/ai/context/process/index.md new file mode 100644 index 0000000..ca6bfb9 --- /dev/null +++ b/ai/context/process/index.md @@ -0,0 +1,12 @@ +# Process Index + +## Stable Process Guides + +- [communication.md](./communication.md) + How to frame technical updates and external communication. + +- [jira-story-rules.md](./jira-story-rules.md) + How to create or reference stories with the right scope and precision. + +- [context-maintenance.md](./context-maintenance.md) + How this workspace should be kept current as living memory. diff --git a/ai/context/process/jira-story-rules.md b/ai/context/process/jira-story-rules.md new file mode 100644 index 0000000..26bdb7d --- /dev/null +++ b/ai/context/process/jira-story-rules.md @@ -0,0 +1,30 @@ +# Jira Story Rules + +## Goal + +Keep Jira updates precise enough that the story reflects the real problem and remains easy to reference later. + +--- + +## Stable Rules + +- Preserve Jira ID and explicit title whenever available. +- Prefer story wording that describes the real contract or behavior gap, not only the first symptom. +- Include authenticated-state or environment qualifiers when they materially affect scope. +- Validate consumer behavior before finalizing scope when the issue depends on Fid4 or flagship. + +--- + +## Story-Creation Guidance + +- Create or refine the story after the reproduction path is understood well enough to avoid mis-scoping. +- Include points and scope only after the work has been framed clearly. +- If the issue crosses SDK, adapter, FT modules, and consumer app boundaries, the story should say so. +- If a bug is external or not yet confirmed as regression, avoid writing the ticket as if the root cause is already proven. + +--- + +## Historical Signals From Slack + +- Historical Slack threads repeatedly show Jeff refining titles and descriptions before stories were created or shared. +- Several story discussions centered on making the wording reflect deeper SwiftUI, lifecycle, or integration issues rather than surface symptoms alone. diff --git a/ai/context/project.md b/ai/context/project.md index 69e289b..eb71d63 100644 --- a/ai/context/project.md +++ b/ai/context/project.md @@ -17,81 +17,47 @@ The product work happens outside this repository, usually from another machine. --- -## Current Priorities +## Stable Context Map -### REST migration +- Core systems live under: + - `ai/context/systems/` +- Durable workstreams live under: + - `ai/context/workstreams/` +- Stable communication and maintenance rules live under: + - `ai/context/process/` +- Named people and role mapping live under: + - `ai/context/people/` -- 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 - -## Historical Slack patterns - -- XFlow SwiftUI migration discussions repeatedly covered Next-button visibility, markdown modal presentation, and custom nav pin/unpin behavior -- Some historical pipeline failures were traced to Apex/ApexKit or Swift preview macro support in the consuming pipeline, not just XFlow itself -- Jeff often requested explicit, polished wording for PR descriptions and cross-team messages -- Historical discussions also surfaced recurring uncertainty around XFlow ownership boundaries versus consumer-app responsibility -- Cross-team dependency issues sometimes involved security, token access, or external pipeline configuration rather than only iOS code changes -- Historical AO and consumer bugs often turned out to be service/configuration issues, incomplete reproduction reports, or consuming-app integration issues rather than XFlow regressions -- Historical integration work repeatedly involved XFlowViewMaker, FTBusiness, FTFrameworks, and Fid4 release/version coupling, especially when validating fixes in real consumer flows +The Slack archive has already been curated into those files so the agent does not need to rediscover the same patterns from raw history every session. --- -## How This Workspace Is Used +## Current Priorities + +- REST migration is replacing GraphQL over time, but REST is still behind a feature flag +- AO and Discourse issues require careful classification because many are incomplete, external, or auth-dependent +- XFlow debugging remains dynamic because behavior changes by entry point, authentication state, backend configuration, and consumer integration +- Consumer validation often depends on Fid4, FT modules, and version propagation, not just SDK behavior + +--- + +## Workspace Use This machine is used to: - maintain current project context - record findings from work performed elsewhere -- capture Mattermost communication that changes understanding +- capture communication that changes technical understanding - prepare polished updates for the current manager or stakeholder - generate standups with better context coverage -This means logs must capture both technical findings and communication context. +This means the context files should hold durable engineering knowledge, while `ai/logs/` and `ai/state/` hold the moving day-to-day view. --- -## People Context +## First Files To Read -- The current manager role is mapped in `ai/context/people/manager.md` -- The active people roster lives in `ai/context/people/index.md` -- Repeatedly relevant named people should have individual files under `ai/context/people/` - ---- - -## 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/context/index.md` +- `ai/context/workstreams/index.md` +- `ai/context/process/communication.md` +- `ai/context/people/index.md` diff --git a/ai/context/systems/fid4.md b/ai/context/systems/fid4.md new file mode 100644 index 0000000..0aba4f0 --- /dev/null +++ b/ai/context/systems/fid4.md @@ -0,0 +1,30 @@ +# Fid4 + +## Role + +Fid4 is the main Fidelity consumer iOS app and the most important environment for validating real integration behavior. + +--- + +## Durable Context + +- Fid4 is the newer flagship-style app and is heavily SwiftUI-based. +- Validation in Fid4 often reveals issues that do not appear in XFlowSDK isolation or sample apps. +- Historical Slack context shows that some tickets were incorrectly scoped until behavior was checked in Fid4 or flagship. +- Real consumer testing in Fid4 matters for modal presentation, validation messaging, and backend-driven flow behavior. + +--- + +## Validation Implications + +- If an issue depends on real flow behavior, do not assume XFlow-only validation is sufficient. +- When a story touches presentation, entry points, or consumer behavior, check whether Fid4 is required to confirm scope. +- Build or startup instability in Fid4 can slow validation and should be treated as a practical investigation constraint. + +--- + +## Historical Signals From Slack + +- Fid4 was repeatedly referenced as the right place to verify SwiftUI/XFlow bugs before finalizing scope. +- Historical work included modal-on-modal presentation issues, goal/date validation behavior, and consumer-facing eventing questions. +- Some XFlow tickets needed rework because the original spike or story had not been validated in flagship/Fid4. diff --git a/ai/context/systems/ftframeworks.md b/ai/context/systems/ftframeworks.md new file mode 100644 index 0000000..bb12156 --- /dev/null +++ b/ai/context/systems/ftframeworks.md @@ -0,0 +1,32 @@ +# FTFrameworks + +## Role + +FTFrameworks contains consumer-side feature modules such as FTAccountOpen, FTTransfer, and related libraries that mediate how XFlow changes reach Fid4. + +--- + +## Durable Context + +- FTFrameworks is often part of the real validation and release chain, not just a downstream detail. +- Historical Slack context shows pinned FT module versions repeatedly blocking adoption of newer XFlow or XFlowViewMaker changes in Fid4. +- Changes to XFlow often needed corresponding FTAccountOpen or FTTransfer updates before end-to-end testing was realistic. + +--- + +## Validation And Release Implications + +- If Fid4 does not reflect the expected XFlow fix, check FT module versions before concluding the SDK change failed. +- Version movement can require a chain such as: + - XFlowSDK + - XFlowViewMaker + - FTAccountOpen / FTTransfer + - Fid4 +- Test failures or publishing issues in FT modules can delay consumer validation even when the core XFlow change is ready. + +--- + +## Historical Signals From Slack + +- FTAccountOpen and FTTransfer were repeatedly mentioned in version bump and release coordination work. +- Historical messages also tied FTFrameworks to FTAuth and MFA-related stories, showing that dependency understanding matters when sizing or scoping work. diff --git a/ai/context/systems/index.md b/ai/context/systems/index.md new file mode 100644 index 0000000..6345db6 --- /dev/null +++ b/ai/context/systems/index.md @@ -0,0 +1,23 @@ +# Systems Index + +## Core Components + +- [fid4.md](./fid4.md) + Consumer app and the most important real-world validation environment. + +- [xflowsdk.md](./xflowsdk.md) + Backend-driven flow engine and the center of most Fidelity behavior analysis. + +- [xflowviewmaker.md](./xflowviewmaker.md) + Adapter layer historically involved in version bumps, release coupling, and removal evaluation. + +- [ftframeworks.md](./ftframeworks.md) + Consumer-side feature modules that often mediate whether XFlow changes can be validated in Fid4. + +--- + +## Guidance + +- Start with `xflowsdk.md` for backend-driven behavior questions. +- Start with `fid4.md` or `ftframeworks.md` for consumer validation and release flow questions. +- Open `xflowviewmaker.md` when the question involves version bumps, transitional architecture, or pipeline friction. diff --git a/ai/context/systems/xflowsdk.md b/ai/context/systems/xflowsdk.md new file mode 100644 index 0000000..9dbaf5f --- /dev/null +++ b/ai/context/systems/xflowsdk.md @@ -0,0 +1,39 @@ +# XFlowSDK + +## Role + +XFlowSDK is the backend-driven UI engine that renders Fidelity flows from service-provided configuration. + +--- + +## Durable Context + +- XFlow behavior depends on backend rules, entry point, and authentication state. +- SwiftUI migration work introduced recurring behavior questions that were not just visual; many were contract or lifecycle issues. +- Historical Slack patterns show recurring topics around: + - component type expansion in SwiftUI + - Next-button visibility rules + - markdown link handling and analytics + - modal presentation and dismissal sequencing + - consumer-vs-framework ownership boundaries + +--- + +## Debugging Implications + +- Do not treat XFlow output as static UI; backend configuration can change the result. +- When behavior differs across environments, check whether the issue is: + - service/configuration driven + - auth-state driven + - entry-point driven + - consumer-integration driven +- Some apparent XFlow regressions historically turned out to be consumer, pipeline, or environment issues. + +--- + +## Historical Signals From Slack + +- SwiftUI behavior repeatedly needed parity work beyond UIKit assumptions. +- Next-button visibility logic required using the full set of service parameters, not only label text. +- Modal, delegate, and lifecycle sequencing became recurring themes in pure SwiftUI environments. +- XFlow work often had to be validated through consumer repositories, not only inside the SDK. diff --git a/ai/context/systems/xflowviewmaker.md b/ai/context/systems/xflowviewmaker.md new file mode 100644 index 0000000..9d21bf8 --- /dev/null +++ b/ai/context/systems/xflowviewmaker.md @@ -0,0 +1,29 @@ +# XFlowViewMaker + +## Role + +XFlowViewMaker is the adapter layer between XFlowSDK and consuming app/framework integration. It is under evaluation for reduction or removal. + +--- + +## Durable Context + +- Historical release work often required bumping XFlowViewMaker alongside XFlowSDK before consumer validation was possible. +- XFlowViewMaker was a recurring source of coupling between XFlow changes and Fid4 or flagship rollout. +- Historical Slack evidence shows that version bumps through XFlowViewMaker were often blocked by external pipeline or dependency issues rather than pure feature regressions. + +--- + +## Integration Implications + +- When a fix exists in XFlowSDK but is not visible in consumer validation, check whether XFlowViewMaker or downstream pinned versions are blocking adoption. +- If the issue involves version propagation into Fid4, treat XFlowViewMaker as part of the release path unless direct-consumption work has replaced it. +- Questions about removing or collapsing the layer should be evaluated against current consumer integration patterns, not just local SDK behavior. + +--- + +## Historical Signals From Slack + +- XFlowViewMaker version bumps into flagship frequently surfaced `PreviewMacros.SwiftUI`, Apex, or pipeline compatibility issues. +- Historical context shows growing pressure to reduce XFlowViewMaker-specific indirection and move toward simpler consumer paths. +- Slack history also shows that tutorials and release steps around XFlowViewMaker were easy to misunderstand, which made version propagation a repeated risk. diff --git a/ai/context/workstreams/ao-discourse.md b/ai/context/workstreams/ao-discourse.md new file mode 100644 index 0000000..c368eb7 --- /dev/null +++ b/ai/context/workstreams/ao-discourse.md @@ -0,0 +1,33 @@ +# AO And Discourse Issues + +## Goal + +Handle externally reported issues without misclassifying scope or over-claiming regression. + +--- + +## Stable Patterns + +- AO and Discourse reports are often incomplete or partially reproducible. +- External reports should be treated as external behavior until verified. +- Many issues only reproduce with authenticated users or in consumer-specific contexts. +- Some historical reports turned out to be service/configuration issues, environment issues, or existing behavior rather than new regressions. + +--- + +## Investigation Rules + +- Always clarify: + - authenticated vs non-authenticated + - reproducibility + - entry point + - whether the issue exists in main + - whether the behavior is external, existing, or regression +- Do not use vague comparison phrases like "same behavior" without scope. + +--- + +## Historical Signals From Slack + +- Historical reports around button visibility, analytics, slot updates, and consumer validation repeatedly required deeper reproduction work before scoping a fix. +- Slack history shows multiple examples where the original ticket or report was not enough to define the real root cause. diff --git a/ai/context/workstreams/consumer-integration.md b/ai/context/workstreams/consumer-integration.md new file mode 100644 index 0000000..9d42439 --- /dev/null +++ b/ai/context/workstreams/consumer-integration.md @@ -0,0 +1,36 @@ +# Consumer Integration And Release + +## Goal + +Capture the durable release and validation path between XFlow changes and real consumer behavior. + +--- + +## Stable Patterns + +- End-to-end validation often requires more than an SDK change. +- Historical Slack evidence shows repeated coupling across: + - XFlowSDK + - XFlowViewMaker + - FTFrameworks modules + - Fid4 / flagship +- Version pins, publishing delays, and consumer build issues can block validation even when the original code change is ready. + +--- + +## Investigation Rules + +- Before concluding a fix is absent in Fid4, check whether the right version actually propagated downstream. +- Separate these failure modes: + - SDK bug + - adapter/version propagation issue + - FT module publish/test issue + - consumer app setup or pipeline issue +- Consumer validation constraints should shape story scope and estimates because they can dominate the real effort. + +--- + +## Historical Signals From Slack + +- Version bump work repeatedly involved XFlowViewMaker, FTAccountOpen, and FTTransfer. +- Some rollout problems involved Jenkins, Apex/ApexKit, preview macro compatibility, or secret/token access rather than the product behavior under investigation. diff --git a/ai/context/workstreams/index.md b/ai/context/workstreams/index.md new file mode 100644 index 0000000..63e76ab --- /dev/null +++ b/ai/context/workstreams/index.md @@ -0,0 +1,26 @@ +# Workstreams Index + +## Active Durable Workstreams + +- [rest-migration.md](./rest-migration.md) + GraphQL deprecation and REST rollout constraints. + +- [ao-discourse.md](./ao-discourse.md) + External issue intake, ambiguity, and authenticated-only reproduction patterns. + +- [xflow-debugging.md](./xflow-debugging.md) + How to reason about backend-driven flows and dynamic behavior. + +- [xflow-swiftui-migration.md](./xflow-swiftui-migration.md) + Historical SwiftUI transition themes that still shape XFlow work. + +- [consumer-integration.md](./consumer-integration.md) + Release and validation coupling across XFlow, XFlowViewMaker, FT modules, and Fid4. + +--- + +## Guidance + +- Open `ao-discourse.md` before classifying external bug reports. +- Open `xflow-debugging.md` for reproduction and investigation framing. +- Open `consumer-integration.md` when the work depends on release propagation or validation in consumer apps. diff --git a/ai/context/workstreams/rest-migration.md b/ai/context/workstreams/rest-migration.md new file mode 100644 index 0000000..d9e44c7 --- /dev/null +++ b/ai/context/workstreams/rest-migration.md @@ -0,0 +1,32 @@ +# REST Migration + +## Goal + +Deprecate GraphQL and Apollo safely while preserving behavior through REST-backed flows. + +--- + +## Stable Constraints + +- REST is behind a feature flag. +- GraphQL remains the default fallback unless confirmed otherwise. +- REST should never be assumed active by default. +- Migration work must preserve behavior parity before removing Apollo-related code. + +--- + +## What Matters In Practice + +- Validation must clarify whether the tested path is actually using REST or still falling back to GraphQL. +- Story scope should distinguish: + - transport migration work + - feature-flag cleanup + - tests and mocks tied to Apollo/GraphQL +- Communication should avoid implying the migration is complete before the fallback path is removed. + +--- + +## Historical Signals From Slack + +- Historical Slack evidence around release and dependency work reinforces that transport or dependency changes often require consumer validation, not just local SDK changes. +- Some dependency and pipeline issues complicated migration-related rollout even when the technical change itself was understood. diff --git a/ai/context/workstreams/xflow-debugging.md b/ai/context/workstreams/xflow-debugging.md new file mode 100644 index 0000000..69093d8 --- /dev/null +++ b/ai/context/workstreams/xflow-debugging.md @@ -0,0 +1,37 @@ +# XFlow Debugging + +## Goal + +Debug backend-driven flows without losing track of dynamic dependencies or misclassifying integration behavior. + +--- + +## Stable Patterns + +- XFlow screens are backend-driven, so UI can change without local code changes. +- Reproduction depends on: + - entry point + - authentication state + - backend configuration + - consumer integration path +- Not all entry points are reachable from visible UI; some require exploratory validation. + +--- + +## Investigation Rules + +- Confirm the entry point before comparing behavior. +- Separate service-driven behavior from client regressions. +- Confirm whether the issue reproduces in: + - sample app + - XFlow-only environment + - Fid4 / flagship + - authenticated vs non-authenticated state +- If a fix appears correct in the SDK but not in consumer validation, inspect the release chain before reopening root cause assumptions. + +--- + +## Historical Signals From Slack + +- Historical debugging covered Next-button visibility, markdown modal analytics, modal presentation, slot updates, and SwiftUI lifecycle behavior. +- Multiple pipeline or dependency problems looked like XFlow issues until the build chain or consumer integration path was inspected more carefully. diff --git a/ai/context/workstreams/xflow-swiftui-migration.md b/ai/context/workstreams/xflow-swiftui-migration.md new file mode 100644 index 0000000..7a5617a --- /dev/null +++ b/ai/context/workstreams/xflow-swiftui-migration.md @@ -0,0 +1,35 @@ +# XFlow SwiftUI Migration + +## Goal + +Track the durable behavior patterns introduced while moving XFlow from older assumptions toward a more complete SwiftUI implementation. + +--- + +## Stable Themes + +- SwiftUI migration was not just a UI rewrite; it exposed contract, lifecycle, and parity gaps. +- Historical Slack evidence repeatedly referenced: + - component type expansion beyond simple string assumptions + - Next-button visibility rules driven by full service parameters + - markdown link handling and analytics integration + - navigation and modal behavior in pure SwiftUI environments + - dismissal delegate lifecycle sequencing + +--- + +## What Matters Now + +- When a SwiftUI issue appears, check whether the missing behavior is: + - parity with UIKit behavior + - an incomplete service contract interpretation + - a lifecycle sequencing problem + - a consumer presentation constraint in Fid4 +- Do not assume a visual issue is only cosmetic; several historical SwiftUI bugs changed flow behavior materially. + +--- + +## Historical Signals From Slack + +- Jeff and Norman repeatedly refined story titles and descriptions around SwiftUI architecture changes, showing that scope wording mattered because the work was often deeper than the first symptom. +- Historical Slack context also shows that SwiftUI-specific work frequently required cross-team clarification when external dependencies or consumer environments behaved differently. diff --git a/ai/logs/2026-04-10.md b/ai/logs/2026-04-10.md index d552030..b34a527 100644 --- a/ai/logs/2026-04-10.md +++ b/ai/logs/2026-04-10.md @@ -10,3 +10,4 @@ - Use the approved title `Remove Apollo for iOS` for `PDIAP-15838`. - When a documentation or root cause update directly supports a story, report it under that story instead of as a separate standup item. - In standups, format Jira references as `ID - Title` or `ID Title`, not `ID, Title`. +- Jeff clarified that `PDIAP-15838` is the next story to work on and `PDIAP-15836` comes later. diff --git a/ai/state/current.md b/ai/state/current.md index aa349a1..ba2115d 100644 --- a/ai/state/current.md +++ b/ai/state/current.md @@ -8,6 +8,7 @@ - Prepare better updates for the current manager or stakeholder through Mattermost - Follow up on `PDIAP-15765`, `PDIAP-15836`, and `PDIAP-15838` - Finalize `PDIAP-14859` with a dual UIKit/SwiftUI plan that removes `UIHostingController` dynamically while preserving both flows appropriately +- Prioritize `PDIAP-15838` next; `PDIAP-15836` comes later --- diff --git a/ai/state/work-items.md b/ai/state/work-items.md index 654477c..d55dd43 100644 --- a/ai/state/work-items.md +++ b/ai/state/work-items.md @@ -10,7 +10,7 @@ Update it only with explicit, project-relevant information that is useful for fu Current note: root cause was documented; the DOB validation issue was confirmed on TeenIdentityCheck for authenticated users, and Jeff approved moving the story to Done once the new sprint starts. - `PDIAP-15836` - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment - Current note: story came out of the AccountLink root cause investigation and related root cause document update; it was sized at 8 points, aligned with epic `26Q2 - Updating XFlowSDK to Decouple and Fix ApexKit Dependencies (Split Part 2)`, and is meant to cover SwiftUI dismissal sequencing validation. + Current note: story came out of the AccountLink root cause investigation and related root cause document update; it was sized at 8 points, aligned with epic `26Q2 - Updating XFlowSDK to Decouple and Fix ApexKit Dependencies (Split Part 2)`, is meant to cover SwiftUI dismissal sequencing validation, and should come after `PDIAP-15838`. - `PDIAP-15838` - Remove Apollo for iOS - Current note: approved at 8 points; description and ACs were filled in and Jeff approved the scope to remove Apollo, GraphQL-specific networking code, related tests and mocks, and transport feature flags so REST remains. + Current note: approved at 8 points; description and ACs were filled in and Jeff approved the scope to remove Apollo, GraphQL-specific networking code, related tests and mocks, and transport feature flags so REST remains. This is the next story to work on before `PDIAP-15836`. diff --git a/opencode.json b/opencode.json index 80bf240..34a549c 100644 --- a/opencode.json +++ b/opencode.json @@ -41,7 +41,12 @@ }, "instructions": [ "./README.md", + "./ai/context/index.md", "./ai/context/project.md", + "./ai/context/systems/index.md", + "./ai/context/workstreams/index.md", + "./ai/context/process/communication.md", + "./ai/context/process/jira-story-rules.md", "./ai/context/people/manager.md", "./ai/context/people/index.md", "./ai/state/current.md", diff --git a/prompts/manager-update.md b/prompts/manager-update.md index 93c4fdf..a3aba52 100644 --- a/prompts/manager-update.md +++ b/prompts/manager-update.md @@ -1,6 +1,6 @@ # Manager Update Prompt -Use the current state, today's log, `ai/context/people/manager.md`, and `ai/context/people/jeff-dewitte.md`. +Use the current state, today's log, `ai/context/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, and `ai/context/people/index.md`. Draft a Mattermost update for the current manager or stakeholder in concise, natural, professional US English. diff --git a/prompts/standup.md b/prompts/standup.md index 7b29dc4..8be4aa8 100644 --- a/prompts/standup.md +++ b/prompts/standup.md @@ -1,6 +1,6 @@ # Standup Prompt -Use `ai/state/current.md`, `ai/state/work-items.md`, `ai/context/project.md`, `ai/context/people/manager.md`, `ai/context/people/jeff-dewitte.md`, yesterday's log, today's log if present, and the latest available Mattermost context. +Use `ai/state/current.md`, `ai/state/work-items.md`, `ai/context/index.md`, `ai/context/project.md`, `ai/context/workstreams/index.md`, `ai/context/process/communication.md`, `ai/context/people/manager.md`, yesterday's log, today's log if present, and the latest available Mattermost context. Generate a standup update for an iOS engineer working on Fidelity. diff --git a/workflows/opencode-entry.md b/workflows/opencode-entry.md index 82f05ab..addc641 100644 --- a/workflows/opencode-entry.md +++ b/workflows/opencode-entry.md @@ -31,6 +31,7 @@ Use OpenCode as the daily AI entry point for this workspace without losing proje - 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. +- Stable context is split by systems, workstreams, process, people, and decisions so the agent can pull the right layer instead of overloading one project file. - Mattermost context can be refreshed into `ai/inbox/` using your existing local sync script. - Direct prompts are also treated as memory opportunities, so the agent can update workspace context during normal conversation. - Daily updates go back into the workspace, so later prompts inherit better context.