Refactor AI workspace for improved context management and communication integration
- Introduced new commands and skills for workspace memory curation, professional communication, and status reporting. - Updated existing commands to utilize new skills and improve clarity in instructions. - Created a new workspace context command to load reusable core and active project profile. - Enhanced Mattermost inbox integration with support for generic environment variables. - Established a clear separation between project-independent core logic and project-specific profiles. - Improved documentation across various files to reflect changes in workflow and command usage. - Added operational memory management rules to ensure accurate context promotion and correction. - Updated README and workflow documents to guide users in utilizing the new structure effectively.
This commit is contained in:
59
core/README.md
Normal file
59
core/README.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# AI Workspace Core
|
||||
|
||||
Reusable operating layer for AI-assisted professional workspaces.
|
||||
|
||||
The core is project-independent. It defines how an AI agent should maintain file-based memory, ingest communication evidence, draft recurring updates, and adjust its own commands, prompts, and skills when reusable behavior changes.
|
||||
|
||||
---
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
- Maintain operational memory across sessions
|
||||
- Separate imported evidence from promoted memory
|
||||
- Provide reusable command and prompt patterns
|
||||
- Support project profiles without embedding project-specific facts in the core
|
||||
- Keep tooling behavior editable by the agent when the user corrects recurring output
|
||||
|
||||
---
|
||||
|
||||
## Project Profiles
|
||||
|
||||
Each real project should provide a profile under `profiles/<project>/`.
|
||||
|
||||
A profile declares:
|
||||
|
||||
- project name and audience
|
||||
- active communication sources
|
||||
- ticket/work-item system
|
||||
- manager or stakeholder mapping
|
||||
- domain-specific context files
|
||||
- enabled commands and skills
|
||||
|
||||
The core should never require a specific company, codebase, manager, channel name, ticket prefix, or programming stack.
|
||||
|
||||
---
|
||||
|
||||
## Memory Layers
|
||||
|
||||
- `daily`: facts from a specific workday
|
||||
- `state`: current active focus and near-term constraints
|
||||
- `work-items`: canonical memory for active units of work
|
||||
- `stable-context`: durable system, domain, process, or architecture knowledge
|
||||
- `people`: role, stakeholder, and collaboration memory
|
||||
- `decisions`: confirmed decisions with ongoing impact
|
||||
- `tooling-behavior`: reusable rules that change commands, prompts, skills, or agent behavior
|
||||
|
||||
See `core/memory/operational-memory.md` for the detailed rules.
|
||||
|
||||
---
|
||||
|
||||
## Integration Model
|
||||
|
||||
Integrations extract evidence. They do not decide what becomes memory.
|
||||
|
||||
- live communication connectors write recent evidence to `ai/inbox/`
|
||||
- historical archive connectors write selected evidence to `scripts/<source>/generated/`
|
||||
- the agent promotes only high-confidence, project-relevant facts into memory
|
||||
|
||||
See `core/integrations/communication-model.md` for the reusable connector contract.
|
||||
|
||||
83
core/integrations/communication-model.md
Normal file
83
core/integrations/communication-model.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Communication Integration Model
|
||||
|
||||
## Principle
|
||||
|
||||
Communication integrations extract evidence. The agent promotes memory.
|
||||
|
||||
Connectors should not decide that a message is durable project truth. They should fetch, normalize, and store evidence in predictable files so the agent can apply memory rules.
|
||||
|
||||
---
|
||||
|
||||
## Connector Types
|
||||
|
||||
### Live Communication Connector
|
||||
|
||||
Use for active systems such as Mattermost, Slack, Teams, or email.
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- fetch recent messages from configured channels or conversations
|
||||
- support a forced refresh for "latest message" prompts
|
||||
- write the latest evidence to `ai/inbox/`
|
||||
- write status separately from project memory
|
||||
- fail safely without updating logs, state, or context
|
||||
|
||||
### Historical Archive Connector
|
||||
|
||||
Use for exports such as Slack archives.
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- read raw archive files from an ignored archive location
|
||||
- select high-signal evidence without treating the archive as current truth
|
||||
- write generated summaries and JSONL to `scripts/<source>/generated/`
|
||||
- preserve enough source metadata for later review
|
||||
|
||||
---
|
||||
|
||||
## Standard Evidence Shape
|
||||
|
||||
Connectors should emit JSONL records with this minimum shape when practical:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "communication-system",
|
||||
"channel": "readable-channel-name",
|
||||
"timestamp": "ISO-8601 timestamp",
|
||||
"username": "display name or handle",
|
||||
"message": "message text",
|
||||
"thread_id": "optional thread id",
|
||||
"metadata": {}
|
||||
}
|
||||
```
|
||||
|
||||
Additional fields are allowed when useful, but the core should not depend on project-specific fields.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Prefer generic `AIW_*` variables for reusable workspaces:
|
||||
|
||||
- `AIW_PROJECT_PROFILE`
|
||||
- `AIW_CHANNEL_PREFIX`
|
||||
- `AIW_MATTERMOST_SYNC_CMD`
|
||||
- `AIW_MATTERMOST_SYNC_INTERVAL_MINUTES`
|
||||
- `AIW_SLACK_EXPORT_PATH`
|
||||
|
||||
Project-specific variables may remain as compatibility aliases, but new integrations should prefer `AIW_*`.
|
||||
|
||||
---
|
||||
|
||||
## Failure Rules
|
||||
|
||||
If a connector fails:
|
||||
|
||||
- record operational status only
|
||||
- do not update daily logs
|
||||
- do not update current state
|
||||
- do not update stable context
|
||||
- do not infer project facts from the failure
|
||||
|
||||
The agent may report the operational failure to the user, but it must not promote the failure as project memory unless the user explicitly asks to track tooling work.
|
||||
|
||||
138
core/memory/operational-memory.md
Normal file
138
core/memory/operational-memory.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Operational Memory
|
||||
|
||||
## Definition
|
||||
|
||||
Operational memory is a versionable file-based system where the agent decides whether each interaction introduces, corrects, or invalidates knowledge, then updates the smallest correct canonical file.
|
||||
|
||||
The goal is not transcript storage. The goal is a curated working memory that improves future reasoning, communication, and execution.
|
||||
|
||||
---
|
||||
|
||||
## Memory Classes
|
||||
|
||||
### `daily`
|
||||
|
||||
Use for same-day progress, findings, evolving reproduction notes, and work that may change soon.
|
||||
|
||||
Default path pattern:
|
||||
|
||||
```text
|
||||
ai/logs/YYYY-MM-DD.md
|
||||
```
|
||||
|
||||
### `state`
|
||||
|
||||
Use for current priorities, active blockers, near-term constraints, and communication needs that affect the next few days.
|
||||
|
||||
Default paths:
|
||||
|
||||
```text
|
||||
ai/state/current.md
|
||||
ai/state/work-items.md
|
||||
```
|
||||
|
||||
### `work-items`
|
||||
|
||||
Use for canonical memory about active tickets, tasks, stories, investigations, or other units of work.
|
||||
|
||||
Default path pattern:
|
||||
|
||||
```text
|
||||
ai/work-items/<id-or-slug>.md
|
||||
```
|
||||
|
||||
### `stable-context`
|
||||
|
||||
Use for durable project knowledge that should survive beyond the current work window.
|
||||
|
||||
Default path pattern:
|
||||
|
||||
```text
|
||||
ai/context/<domain>/*.md
|
||||
```
|
||||
|
||||
### `people`
|
||||
|
||||
Use for repeated collaborators, role mappings, manager/stakeholder context, and communication preferences.
|
||||
|
||||
Default path pattern:
|
||||
|
||||
```text
|
||||
ai/context/people/*.md
|
||||
```
|
||||
|
||||
### `decisions`
|
||||
|
||||
Use for confirmed decisions with ongoing impact.
|
||||
|
||||
Default path pattern:
|
||||
|
||||
```text
|
||||
ai/context/decisions/*.md
|
||||
```
|
||||
|
||||
### `tooling-behavior`
|
||||
|
||||
Use when a user correction changes how the workspace should behave in the future.
|
||||
|
||||
Default path patterns:
|
||||
|
||||
```text
|
||||
.opencode/commands/*.md
|
||||
.opencode/agents/*.md
|
||||
.opencode/skills/*/SKILL.md
|
||||
prompts/*.md
|
||||
knowledge/*.md
|
||||
ai/context/process/*.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Promotion Rules
|
||||
|
||||
Promote information when it is:
|
||||
|
||||
- explicit enough to preserve safely
|
||||
- relevant to the current project or workflow
|
||||
- likely to matter in a future session
|
||||
- useful for standups, status updates, debugging, planning, or decision making
|
||||
|
||||
Do not promote:
|
||||
|
||||
- tool failures
|
||||
- sync attempts
|
||||
- empty inbox states
|
||||
- generic chat noise
|
||||
- unverified guesses
|
||||
- duplicate paraphrases of existing memory
|
||||
|
||||
If confidence is mixed, prefer the daily log and preserve uncertainty.
|
||||
|
||||
---
|
||||
|
||||
## Correction Rules
|
||||
|
||||
When new information supersedes old memory:
|
||||
|
||||
- update the existing canonical file directly
|
||||
- do not leave stale and corrected versions side by side
|
||||
- preserve qualifiers when the fact remains partially confirmed
|
||||
- update indexes when adding new stable context files
|
||||
|
||||
The agent should behave like a senior engineer maintaining project notes, not like a transcript accumulator.
|
||||
|
||||
---
|
||||
|
||||
## Self-Maintenance Rules
|
||||
|
||||
When the user corrects recurring output or behavior, update the operational surface that controls that behavior.
|
||||
|
||||
Examples:
|
||||
|
||||
- standup format correction -> update `prompts/standup.md` and the standup command
|
||||
- communication freshness correction -> update the communication sync command/plugin
|
||||
- prompt-engineering correction -> update the AI prompt command or skill
|
||||
- memory routing correction -> update memory rules and context-maintenance guidance
|
||||
|
||||
The daily log may preserve evidence, but reusable behavior must live in the command, prompt, skill, agent, or knowledge file that enforces it.
|
||||
|
||||
88
core/profiles/create-project-profile.md
Normal file
88
core/profiles/create-project-profile.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Create A Project Profile
|
||||
|
||||
Use this checklist when adapting the workspace core for a new project.
|
||||
|
||||
---
|
||||
|
||||
## 1. Create The Profile
|
||||
|
||||
Create:
|
||||
|
||||
```text
|
||||
profiles/<project>/profile.md
|
||||
profiles/<project>/README.md
|
||||
```
|
||||
|
||||
The profile should declare:
|
||||
|
||||
- project name
|
||||
- workspace purpose
|
||||
- primary audience
|
||||
- communication sources
|
||||
- ticket/work-item system
|
||||
- manager or stakeholder mapping
|
||||
- active context files
|
||||
- enabled commands
|
||||
- enabled skills
|
||||
|
||||
---
|
||||
|
||||
## 2. Configure Context
|
||||
|
||||
Create or update:
|
||||
|
||||
```text
|
||||
ai/context/project.md
|
||||
ai/context/index.md
|
||||
ai/context/process/
|
||||
ai/context/people/
|
||||
ai/state/current.md
|
||||
ai/state/work-items.md
|
||||
ai/work-items/index.md
|
||||
```
|
||||
|
||||
Keep project-specific facts out of `core/`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Configure Integrations
|
||||
|
||||
Use generic variables first:
|
||||
|
||||
```text
|
||||
AIW_PROJECT_PROFILE=<project>
|
||||
AIW_CHANNEL_PREFIX=<project-or-team-prefix>
|
||||
AIW_MATTERMOST_SYNC_CMD=<optional custom command>
|
||||
AIW_SLACK_EXPORT_PATH=<optional archive path>
|
||||
```
|
||||
|
||||
Connector secrets belong in ignored `.env` files, not in profile files.
|
||||
|
||||
---
|
||||
|
||||
## 4. Configure Commands And Skills
|
||||
|
||||
Start with generic commands:
|
||||
|
||||
- `/workspace-context`
|
||||
- `/communication-sync`
|
||||
- `/archive-import`
|
||||
- `/standup`
|
||||
- `/manager-update`
|
||||
- `/translate`
|
||||
- `/ai-prompt`
|
||||
|
||||
Add project-specific aliases only when they reduce friction.
|
||||
|
||||
---
|
||||
|
||||
## 5. Validate
|
||||
|
||||
Before using the workspace for real work:
|
||||
|
||||
- confirm `opencode.json` is valid JSON
|
||||
- confirm the profile has no secrets
|
||||
- run a communication sync with test channels or a dry sample
|
||||
- generate one standup from sample context
|
||||
- verify that imported evidence and promoted memory stay separate
|
||||
|
||||
Reference in New Issue
Block a user