david.delagneau/fidelity-ai-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add initial project architecture, concepts, and quick-start documentation

Browse Source
This commit is contained in:
David Delagneau
2026-05-22 09:26:53 -06:00
parent 7594e8ebc9
commit 60868b9c96
6 changed files with 567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/README.md Normal file
View File

@@ -0,0 +1,31 @@
# AIWorkspace Documentation
AIWorkspace is a local context platform for developers. It connects project evidence, canonical human-readable memory, local services, and AI clients without making any single AI tool the source of truth.
This documentation describes the target production architecture: reusable AIWorkspace core separated from project-specific AI context packs.
## Start Here
- [Concepts: Overview](concepts/overview.md)
- [Concepts: Workspace vs Context Pack](concepts/workspace-vs-context-pack.md)
- [Architecture: Storage Model](architecture/storage-model.md)
- [Guide: Quick Start](guides/quick-start.md)
- [Reference: Project Manifest](reference/project-manifest.md)
## Documentation Map
```text
docs/
concepts/ Product concepts and user-facing mental model
architecture/ System boundaries, storage, services, and security
guides/ Task-oriented setup and usage guides
reference/ File formats, CLI, manifests, and environment variables
```
## Core Principle
```text
AIWorkspace provides context. Project context packs own project memory.
```
The core product should remain reusable and shareable. Project-specific facts, connector settings, people, channels, raw evidence, and prompts belong in separate context packs.

98
docs/architecture/storage-model.md Normal file
View File

@@ -0,0 +1,98 @@
# Storage Model
AIWorkspace uses different storage locations for different kinds of data. This keeps the product shareable, the project context auditable, and local runtime state disposable.
## Storage Responsibilities
| Data | Target Location | Git? | Notes |
|---|---|---:|---|
| Core product code | `~/Developer/ai-workspace` | yes | Shared reusable product. |
| Project manifest | `<context-pack>/aiw.project.json` | yes | Project identity and relative paths. |
| Canonical memory | `<context-pack>/knowledge/` | usually yes | Human-readable Markdown. |
| Raw evidence | `<context-pack>/inbox/` | usually no/private | Captured messages, screenshots, exports. |
| Connector config | `<context-pack>/connectors/` | depends | Safe config can be tracked; secrets must not be tracked. |
| Project prompts/agents | `<context-pack>/prompts/`, `<context-pack>/agents/` | depends | Track if safe for the team. |
| User registry | `~/Library/Application Support/AIWorkspace/` | no | Local project registration and preferences. |
| Logs | `~/Library/Logs/AIWorkspace/` | no | Service and app logs. |
| Caches/indexes | `~/Library/Caches/AIWorkspace/` | no | Rebuildable derived data. |
| Runtime/PIDs | `~/Library/Application Support/AIWorkspace/runtime/` | no | Local service state. |
## Canonical Memory
Canonical memory is the durable project source of truth for humans and AI.
Target structure:
```text
knowledge/
current/
work-items/
systems/
workstreams/
people/
decisions/
daily/
templates/
```
Canonical memory should be:
- readable without AIWorkspace;
- reviewable in Git when shared;
- explicit about uncertainty;
- updated by humans or agents using small auditable changes.
## Raw Evidence
Raw evidence is input, not truth.
Examples:
```text
inbox/
mattermost/
slack/
photos/
documents/
screenshots/
```
Raw evidence should not be promoted automatically into durable memory unless a workflow explicitly classifies it as high-confidence and project-relevant.
## Derived Indexes
Indexes are rebuildable.
They should live outside the context pack by default:
```text
~/Library/Caches/AIWorkspace/indexes/<project>/
```
This prevents large derived artifacts from polluting project memory repositories.
## Runtime State
Service logs, PID files, and health snapshots should be local machine state.
Target locations:
```text
~/Library/Logs/AIWorkspace/
~/Library/Application Support/AIWorkspace/runtime/
```
Runtime state should not be used as project memory.
## Secrets
Secrets should not be stored in context packs unless they are encrypted and explicitly supported.
Preferred approaches:
- macOS Keychain references;
- ignored local `.env` files;
- environment variables;
- enterprise-approved credential stores.
Documentation, manifests, and generated configs should refer to secret names, not secret values.

65
docs/concepts/overview.md Normal file
View File

@@ -0,0 +1,65 @@
# AIWorkspace Overview
AIWorkspace helps developers give AI tools the right project context at the right time.
It is designed for teams and individuals who use multiple AI clients—OpenCode, GitHub Copilot, Claude Code, Cursor, VS Code, or others—but do not want project knowledge scattered across chat histories, prompt files, and product repositories.
## What AIWorkspace Does
AIWorkspace provides a local platform to:
- connect communication and evidence sources;
- keep canonical project memory in human-readable Markdown;
- index that memory for fast retrieval;
- expose bounded context through MCP;
- generate AI client configuration when needed;
- run local services such as context servers, capture proxies, and inbox receivers;
- keep raw evidence separate from curated project knowledge.
## What AIWorkspace Is Not
AIWorkspace is not:
- a replacement for a product repository;
- a replacement for project documentation;
- a cloud memory system;
- a single-agent framework that forces one AI workflow;
- a place to store secrets in Git;
- a dumping ground for raw chat exports.
## Target User Flow
```text
Developer installs AIWorkspace
↓
Registers or creates a project context pack
↓
Connects evidence sources and local repos
↓
AIWorkspace captures evidence and maintains indexes
↓
AI clients ask AIWorkspace MCP for project context
↓
Humans and agents update canonical project memory
```
## Key Concepts
| Concept | Meaning |
|---|---|
| AIWorkspace Core | The reusable app, CLI, scripts, MCP server, connectors, templates, and documentation. |
| User Registry | Local app configuration that remembers registered projects, paths, preferences, and service state. |
| Project Context Pack | A project-specific folder or repo containing canonical memory, connector config, prompts, and optional raw evidence. |
| Canonical Memory | Human-readable Markdown that represents current durable project knowledge. |
| Raw Evidence | Captured messages, screenshots, exports, logs, or documents before curation. |
| AI Client | Any tool that consumes context: OpenCode, Copilot, Claude Code, Cursor, VS Code, etc. |
## Design Goal
AIWorkspace should be plug-and-play for a new developer:
1. install the app and CLI;
2. register an existing context pack or create a new one;
3. connect sources such as Mattermost, Slack, tickets, email, calendar, or local folders;
4. let AIWorkspace detect repositories and services;
5. use any AI client with project-aware context through MCP.

127
docs/concepts/workspace-vs-context-pack.md Normal file
View File

@@ -0,0 +1,127 @@
# Workspace vs Context Pack
AIWorkspace separates the installed product, user-local settings, and project memory.
This distinction keeps the system simple, shareable, and safe for unrelated projects such as `client-mobile` and `it-support`.
## Three-Layer Model
```text
AIWorkspace Core
reusable installed product
User/App Registry
local machine settings and registered context packs
Project Context Packs
one isolated context package per project, client, or workstream
```
## AIWorkspace Core
The core is the reusable product. It can be shared with a team.
Typical location during development:
```text
~/Developer/ai-workspace
```
It contains:
```text
apps/
scripts/
connectors/
templates/
docs/
examples/
```
It should not contain real project memory, captured messages, customer names, ticket details, or private prompts.
## User/App Registry
The registry is local to one developer machine. It records which context packs are available and which project is active.
On macOS, the target location is:
```text
~/Library/Application Support/AIWorkspace/
```
Example registry:
```json
{
"schema": "aiworkspace.projects.v1",
"default_project": "client-mobile",
"projects": [
{
"id": "client-mobile",
"context_path": "/Users/david/Developer/client-mobile-ai-context"
},
{
"id": "it-support",
"context_path": "/Users/david/Developer/it-support-ai-context"
}
]
}
```
The registry is not intended for Git.
## Project Context Pack
A context pack is the portable project-specific unit. It may be a private repo, a team-shared repo, or a local folder.
Example:
```text
client-mobile-ai-context/
aiw.project.json
knowledge/
inbox/
connectors/
agents/
prompts/
```
Each context pack owns its own:
- canonical memory;
- raw evidence;
- connector definitions;
- people/channel/system maps;
- prompts and agent instructions specific to that project.
## Why Not Store Everything In One Workspace Repo?
One developer can work on unrelated projects. A single monolithic workspace can accidentally mix:
- channels from different organizations;
- people maps from unrelated clients;
- raw evidence with different privacy rules;
- prompts that only make sense for one domain;
- AI behavior learned from one project but harmful in another.
Context packs prevent this by making project boundaries explicit.
## Optional Product Repository Binding
Product repositories should stay clean by default. If useful, a repo can contain a small optional binding file:
```text
.aiworkspace.json
```
Example:
```json
{
"project": "client-mobile",
"context_path": "/Users/david/Developer/client-mobile-ai-context"
}
```
This file should point to context. It should not contain memory, secrets, or raw evidence.

121
docs/guides/quick-start.md Normal file
View File

@@ -0,0 +1,121 @@
# Quick Start
This guide describes the target production flow for a new developer using AIWorkspace.
The current repository still contains an active project-specific implementation. During refactor, these commands may be implemented incrementally.
## 1. Install AIWorkspace
Install the app, CLI, and local services from the reusable core repo:
```bash
git clone <team-ai-workspace-repo> ~/Developer/ai-workspace
cd ~/Developer/ai-workspace
```
The target CLI entry point is:
```bash
aiw
```
During development, commands may still be run through Python scripts.
## 2. Register Or Create A Project Context Pack
Register an existing context pack:
```bash
aiw project register ~/Developer/client-mobile-ai-context
```
Or create a new one:
```bash
aiw project create it-support --display-name "IT Support" --path ~/Developer/it-support-ai-context
```
The context pack contains project memory and project-specific connector configuration.
## 3. Connect Evidence Sources
Add only the connectors this project needs:
```bash
aiw connector add mattermost --project client-mobile
aiw connector add photos --project client-mobile
```
For another project, the connector set may be completely different:
```bash
aiw connector add tickets --project it-support
aiw connector add calendar --project it-support
```
## 4. Detect Local Repositories
AIWorkspace should help detect local repos and associate them with projects:
```bash
aiw repo scan ~/Developer --project it-support
```
For projects whose source code lives on another machine, the context pack should say so explicitly in `aiw.project.json`.
## 5. Start Context Services
Start services for the active project:
```bash
aiw services start --project client-mobile
aiw services status --project client-mobile
```
The service manager should start only capabilities configured for that project.
## 6. Configure AI Clients
Generate AI client integration files on demand:
```bash
aiw agent configure opencode --project client-mobile
aiw agent configure copilot --project client-mobile
aiw mcp config --client vscode
```
The preferred integration path is MCP, so AI clients can request current context without copying memory into product repositories.
## 7. Use AIWorkspace From Any AI Tool
The AI client should call MCP with a project id:
```json
{
"project": "client-mobile"
}
```
Example tool calls:
```text
project_current_context(project="client-mobile")
project_search_memory(project="it-support", query="printer onboarding")
communication_latest(project="client-mobile")
```
## 8. Keep Canonical Memory Clean
Project memory lives in the context pack:
```text
<context-pack>/knowledge/
```
Raw evidence lives separately:
```text
<context-pack>/inbox/
```
Do not treat raw captures, indexes, logs, or AI chat history as canonical memory.

125
docs/reference/project-manifest.md Normal file
View File

@@ -0,0 +1,125 @@
# Project Manifest Reference
Each project context pack is described by an `aiw.project.json` file at the root of the context pack.
The manifest defines project identity, storage paths, connectors, code locations, and AI client preferences. Paths are relative to the context pack unless explicitly absolute.
## Minimal Manifest
```json
{
"schema": "aiworkspace.project.v1",
"id": "my-project",
"display_name": "My Project",
"knowledge_dir": "knowledge",
"inbox_dir": "inbox"
}
```
## Full Example
```json
{
"schema": "aiworkspace.project.v1",
"id": "client-mobile",
"display_name": "Client Mobile",
"description": "Project context pack for a mobile application team.",
"knowledge_dir": "knowledge",
"inbox_dir": "inbox",
"connectors_dir": "connectors",
"prompts_dir": "prompts",
"agents_dir": "agents",
"connectors": {
"mattermost": {
"enabled": true,
"config": "connectors/mattermost.json"
},
"photos": {
"enabled": true,
"config": "connectors/photos.json"
}
},
"code_locations": [
{
"name": "Development machine",
"availability": "remote-machine"
}
],
"ai_clients": {
"opencode": {
"enabled": true
},
"copilot": {
"enabled": true
}
}
}
```
## Fields
| Field | Required | Description |
|---|---:|---|
| `schema` | yes | Manifest schema version. Current target: `aiworkspace.project.v1`. |
| `id` | yes | Stable lowercase project id used by CLI and MCP. |
| `display_name` | yes | Human-friendly project name. |
| `description` | no | Short project description. |
| `knowledge_dir` | yes | Canonical Markdown memory directory. |
| `inbox_dir` | yes | Raw evidence directory. |
| `connectors_dir` | no | Directory for connector configs. Defaults to `connectors`. |
| `prompts_dir` | no | Directory for project prompts. Defaults to `prompts`. |
| `agents_dir` | no | Directory for project agent config. Defaults to `agents`. |
| `connectors` | no | Connector registry for this project. |
| `code_locations` | no | Local or remote code locations associated with this project. |
| `ai_clients` | no | AI client integration preferences. |
## Code Locations
Code may be local, remote, or unavailable on the current machine.
```json
{
"name": "iOS App",
"path": "/Users/dev/Developer/app-ios",
"role": "consumer-app",
"availability": "local"
}
```
Supported target availability values:
- `local`
- `remote-machine`
- `not-configured`
- `unknown`
## Connector Configs
Connector definitions should describe source behavior without storing secrets.
Example `connectors/mattermost.json`:
```json
{
"schema": "aiworkspace.connector.mattermost.v1",
"enabled": true,
"context_channels": [
"team-standup",
"team-code-review"
],
"secret_refs": {
"session": "keychain:aiworkspace/mattermost/session"
}
}
```
## Validation Rules
A production-ready manifest validator should check:
- required fields exist;
- project id is stable and path-safe;
- configured directories exist or can be created;
- connector config files exist when enabled;
- secrets are referenced, not embedded;
- code locations are explicit about local vs remote availability.