368 lines
12 KiB
Markdown
368 lines
12 KiB
Markdown
# AI Workspace - Fidelity Profile
|
|
|
|
Reusable AI-native companion workspace with Fidelity configured as the first real project profile.
|
|
|
|
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/`. The clean project second brain lives in `project-knowledge/`. Agent operating memory lives in `agent-memory/`. Fidelity-specific setup lives in the active profile under `profiles/fidelity/`.
|
|
|
|
Shared cross-platform workflow/rule content lives in `.agents/`. OpenCode reads that content through `.opencode/` compatibility paths, and Gemini-compatible entry context starts at `GEMINI.md`.
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
### /project-knowledge
|
|
|
|
Canonical Obsidian second brain and transferable project knowledge.
|
|
|
|
- `00-start/` -> onboarding, glossary, and start-here
|
|
- `01-current/` -> current work and active work-item summary
|
|
- `02-work-items/` -> ticket/task notes with metadata properties
|
|
- `03-context/` -> systems, workstreams, project-facing process, and iOS context
|
|
- `04-people/` -> people, roles, and collaboration context
|
|
- `05-decisions/` -> durable decisions
|
|
- `06-daily/` -> daily notes
|
|
- `07-maps/` -> graph hubs and semantic maps
|
|
- `08-bases/` -> Obsidian Bases
|
|
- `09-templates/` -> Obsidian templates
|
|
- `attachments/` -> vault assets
|
|
|
|
### /agent-memory
|
|
|
|
Agent operating memory.
|
|
|
|
- `behavior/` -> agent learning and self-maintenance rules
|
|
- `memory/` -> promotion, correction, and context-maintenance rules
|
|
- `integrations/` -> memory interface, Obsidian adapter, communication sources, and technical verification
|
|
- `workflows/` -> AI-to-AI prompting and workspace behavior model
|
|
- `maps/` -> agent-side navigation maps
|
|
|
|
### /.agents
|
|
|
|
Shared cross-platform workflow and rule source.
|
|
|
|
- `workflows/` -> reusable workflow definitions used by OpenCode-compatible commands and Antigravity-compatible workflow views
|
|
- `rules/` -> reusable skill/rule content
|
|
- `skills/` -> skill-path compatibility layer pointing at `rules/`
|
|
|
|
### /.opencode
|
|
|
|
OpenCode runtime surface.
|
|
|
|
- `commands/` -> OpenCode slash commands, currently linked to `.agents/workflows/`
|
|
- `skills/` -> OpenCode skills, currently linked to shared `.agents/` content
|
|
- `agents/` -> OpenCode agent definitions
|
|
- `plugins/` -> OpenCode-specific plugins
|
|
|
|
### /core
|
|
|
|
Project-independent workspace logic.
|
|
|
|
- `README.md` -> reusable operating model
|
|
- `memory/operational-memory.md` -> reusable 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
|
|
|
|
---
|
|
|
|
## Runtime Structure
|
|
|
|
### /ai
|
|
|
|
Runtime inbox for communication evidence.
|
|
|
|
- `inbox/` -> communication evidence and transient inbox files before promotion into `project-knowledge/`
|
|
|
|
### /prompts
|
|
|
|
Reusable prompts for:
|
|
|
|
- standups
|
|
- Mattermost updates
|
|
- manager communication
|
|
- issue clarification
|
|
|
|
### /workflows
|
|
|
|
Repeatable working guides for:
|
|
|
|
- daily context sync
|
|
- flow debugging
|
|
- external issue analysis
|
|
|
|
### /scripts
|
|
|
|
Helpers for automation around memory access, context generation, communication drafting, and imports.
|
|
|
|
- `scripts/aiw/` -> local AI Workspace service manager for profile services such as the Mattermost proxy mirror, Photo Inbox, and future context MCP
|
|
- `scripts/memory/` -> project-agnostic interface for canonical memory
|
|
- `scripts/obsidian/` -> current Obsidian adapter and URI helpers
|
|
- `scripts/mattermost/` -> live communication connector
|
|
- `scripts/slack/` -> historical archive importer
|
|
|
|
### /project-knowledge/.obsidian
|
|
|
|
Optional Obsidian vault configuration.
|
|
|
|
Open `project-knowledge/` as the Obsidian vault. Do not open the repository root as the vault.
|
|
|
|
Portable vault configuration can be versioned, while local layout and plugin runtime files are ignored.
|
|
|
|
Obsidian is the current visual interface over canonical memory. The reusable memory access layer is `scripts/memory/`, so the workspace can later swap Obsidian for another Markdown knowledge tool without changing the memory model.
|
|
|
|
---
|
|
|
|
## Daily Usage
|
|
|
|
### Start of day
|
|
|
|
Read:
|
|
|
|
- `project-knowledge/00-start/start-here.md`
|
|
- `project-knowledge/01-current/current-work.md`
|
|
- `project-knowledge/01-current/work-items.md`
|
|
- `project-knowledge/03-context/project.md`
|
|
- `project-knowledge/04-people/manager.md`
|
|
- `project-knowledge/04-people/index.md`
|
|
- latest file under `project-knowledge/06-daily/`
|
|
|
|
### 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:
|
|
|
|
- `project-knowledge/06-daily/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:
|
|
|
|
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 `/workspace-context` or the Fidelity alias `/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:
|
|
|
|
- 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.
|
|
|
|
Cross-platform note:
|
|
|
|
- `.agents/` is the shared source of truth for reusable workflows/rules
|
|
- `.opencode/` is the OpenCode execution layer
|
|
- `.agent/` may exist as a naming alias for tools that look for singular agent directories
|
|
- `GEMINI.md` is the Gemini CLI entrypoint for shared workspace context
|
|
|
|
---
|
|
|
|
## Generic Commands
|
|
|
|
- `/workspace-context` -> load core plus active profile
|
|
- `/memory-health` -> check canonical memory and adapter health
|
|
- `/memory-create` -> create a typed canonical note through the memory interface
|
|
- `/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:
|
|
|
|
1. Use the workspace-local script at `scripts/mattermost/sync.sh`, or override it with `AIW_MATTERMOST_SYNC_CMD`.
|
|
2. Let OpenCode run with the project plugins enabled.
|
|
3. The Mattermost inbox plugin will periodically refresh `ai/inbox/mattermost-latest.md`.
|
|
4. Promote durable facts from the inbox into `project-knowledge/06-daily/`, `project-knowledge/01-current/`, `project-knowledge/02-work-items/`, and `project-knowledge/03-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 `FIDELITY_*` variables remain supported as Fidelity-profile aliases, but new reusable setup should prefer `AIW_*`.
|
|
|
|
---
|
|
|
|
## Project Knowledge Vault
|
|
|
|
Open `project-knowledge/` as the Obsidian vault. The repository root remains the technical workspace for OpenCode, scripts, profiles, runtime inboxes, and generated evidence.
|
|
|
|
Recommended entry point:
|
|
|
|
- `project-knowledge/00-start/start-here.md`
|
|
- `project-knowledge/00-start/onboarding.md` for new members
|
|
- `project-knowledge/00-start/glossary.md` for terminology
|
|
- `project-knowledge/07-maps/` for graph hubs
|
|
|
|
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 under `project-knowledge/`.
|
|
|
|
Runtime/evidence stays outside the vault:
|
|
|
|
- `.opencode/`
|
|
- `scripts/`
|
|
- `core/`
|
|
- `profiles/`
|
|
- `ai/inbox/`
|
|
- `scripts/*/generated/`
|
|
|
|
Ignored Obsidian runtime files include workspace layout, plugin cache, snippets, and local plugin installs.
|
|
|
|
Project-agnostic memory helpers live under `scripts/memory/`:
|
|
|
|
- `scripts/memory/memory.sh create <type> <slug> [title]`
|
|
- `scripts/memory/memory.sh search <query> [folder]`
|
|
- `scripts/memory/memory.sh base-query <base-name> [format]`
|
|
- `scripts/memory/memory.sh health`
|
|
|
|
Obsidian adapter helpers live under `scripts/obsidian/`:
|
|
|
|
- `scripts/obsidian/cli.sh <obsidian-cli-command>`
|
|
- `scripts/obsidian/open.sh <vault-relative-path>`
|
|
- `scripts/obsidian/daily.sh`
|
|
- `scripts/obsidian/search.sh <query>`
|
|
- `scripts/obsidian/uri.sh <action> key=value`
|
|
|
|
---
|
|
|
|
## Creating Another Project
|
|
|
|
1. Copy `profiles/example/` to `profiles/<project>/`.
|
|
2. Fill in `profiles/<project>/profile.md`.
|
|
3. Set `AIW_PROJECT_PROFILE=<project>`.
|
|
4. Configure any communication connector with `AIW_*` variables.
|
|
5. Create or adapt `project-knowledge/` for the project-specific canonical memory.
|
|
6. Use `/workspace-context` to load the core plus active profile.
|
|
|
|
See `core/profiles/create-project-profile.md` for the full checklist.
|