KTA Cleanup for shareout (#636)

Author: payneio

assistants/knowledge-transfer-assistant/CLAUDE.md

@@ -2,176 +2,170 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Knowledge Transfer Assistant
+# Knowledge Transfer Assistant
 
-A dual-mode context transfer system that facilitates collaborative knowledge sharing between Coordinators and Team members in the Semantic Workbench. This assistant bridges information gaps through structured communication with shared artifacts, real-time updates, and bidirectional information flow.
+A sophisticated dual-mode assistant that facilitates collaborative knowledge sharing between Coordinators (knowledge creators) and Team members (knowledge receivers) within the Semantic Workbench platform.
 
-## Architecture Overview
+## Core Architecture
 
-### Dual Mode Operation
+### Dual-Mode Operation
+The assistant operates in two distinct modes with role-specific capabilities:
 
-The assistant operates in two distinct conversation roles determined by metadata:
-
-1. **Coordinator Mode**: Knowledge organizers create and manage knowledge bases, provide guidance, and respond to information requests
-2. **Team Mode**: Team members access shared knowledge, explore project context, and request additional information
-
-**Role Detection**: Uses `detect_assistant_role()` to check conversation metadata `project_role` field. Capabilities are role-specific through tool registration.
-
-### Conversation Structure
+1. **Coordinator Mode**: Creates and manages knowledge packages, responds to information requests, shares files
+2. **Team Mode**: Accesses shared knowledge, requests information, tracks learning progress
 
+### Cross-Conversation Communication
 The system manages three types of conversations:
-
-- **Coordinator Conversation**: Personal workspace for knowledge organizers
-- **Shareable Team Conversation**: Template conversation with share URL (never directly used)
-- **Team Conversation(s)**: Individual conversations for team members accessing shared knowledge
+- **Coordinator Conversation**: Personal workspace for knowledge creation
+- **Shareable Team Conversation**: Template conversation (never directly used)
+- **Team Conversation(s)**: Individual conversations for each team member
 
 ### Key Components
 
-- `assistant/assistant.py`: Main assistant implementation with dual-role event handling
-- `assistant/manager.py`: Project state and artifact management (KnowledgeTransferManager)
-- `assistant/conversation_share_link.py`: Cross-conversation linking and synchronization
-- `assistant/inspectors/`: Modular inspector panel system (brief, learning, sharing, debug)
-- `assistant/notifications.py`: Cross-conversation notification and UI refresh system
-- `assistant/storage.py` & `assistant/storage_models.py`: Persistent state management
-- `assistant/config.py`: Role-specific prompt templates and configuration
-- `assistant/data.py`: Core data models and enums (including InspectorTab)
-
-## Common Commands
-
-- Build/Install: `make install`
-- Format: `make format` (runs ruff formatter)
-- Lint: `make lint` (runs ruff linter)
-- Type-check: `make type-check` (runs pyright)
-- Test: `make test` (runs pytest)
-- Single test: `uv run pytest tests/test_file.py::test_function -v`
-- Manual inspector test: `python tests/test_inspector.py` (test state inspector functionality)
-- Docker build: `make docker-build` (builds assistant container image)
-- Start assistant: `make start` (starts the assistant service)
-- Local docker run: `make docker-run-local` (runs assistant in Docker with local workbench)
-
-## Development Notes
-
-### Inspector Panel UI Refresh System
-
-The assistant uses a sophisticated event-driven system to keep inspector panels synchronized across all conversations:
-
-- **InspectorTab Enum**: Defines available inspector panels with their state IDs (`data.py`)
-- **refresh_current_ui()**: Updates inspector panels in the current conversation only
-- **refresh_all_project_uis()**: Updates inspector panels across all conversations in a project
-- **ProjectNotifier.notify_project_update()**: Sends notifications and refreshes UIs with optional tab targeting
-- **State Events**: Uses `AssistantStateEvent` with specific state IDs to trigger UI updates
-
-**Key Pattern**: When updating project state, always call the appropriate refresh function with specific tabs:
-```python
-from .data import InspectorTab
-await ShareStorage.refresh_all_share_uis(context, share_id, [InspectorTab.BRIEF])
-```
+- **Knowledge Transfer Manager** (`assistant/domain/`): Orchestrates the entire knowledge transfer lifecycle
+- **Share Manager** (`assistant/files.py`): Handles file synchronization across conversations
+- **Storage System** (`assistant/storage.py`, `assistant/storage_models.py`): Persistent state management
+- **UI Tabs** (`assistant/ui-tabs/`): Real-time visual dashboards showing transfer status
+- **Notification System** (`assistant/notifications.py`): Cross-conversation communication
 
-### State Management
+### Core Artifacts
+- **Knowledge Brief**: Introductory overview for team members
+- **Knowledge Digest**: Auto-updating LLM-generated information repository
+- **Learning Objectives**: Structured goals with specific outcomes
+- **Information Requests**: Team member questions with priority levels
 
-- **Cross-Conversation Linking**: Connects coordinator and team conversations through project IDs
-- **File Synchronization**: Automatic file sharing between linked conversations
-- **Artifact Storage**: Structured data models for project briefs, knowledge digests, and information requests
-- **Inspector Panel System**: Multi-panel real-time dashboard with specific state IDs:
-  - `brief`: Knowledge brief and project overview
-  - `objectives`: Learning objectives and outcomes
-  - `requests`: Information requests and sharing status
-  - `debug`: Debug information and project state
-- **UI Refresh Architecture**: Event-driven system using `AssistantStateEvent` with specific state IDs
-- **Auto-Update Knowledge Digest**: LLM-powered automatic extraction and updating of key information from conversations
+## Development Commands
 
-### Auto-Update Knowledge Digest
+### Basic Operations
+```bash
+# Install dependencies
+make install
 
-The system automatically extracts and updates key information from conversations:
+# Run all tests
+make test
 
-- **Trigger**: Every Coordinator message automatically triggers `auto_update_knowledge_digest()`
-- **Process**: Analyzes chat history using LLM to extract important information
-- **Storage**: Updates the knowledge digest with extracted content marked as auto-generated
-- **UI Refresh**: Ensures debug panel refreshes after completion (both success and error cases)
-- **Pattern**: Always refreshes UI regardless of success/failure to maintain consistency
+# Run specific test with verbose output
+uv run pytest tests/test_file.py::test_function -v
 
-### Configuration Templates
+# Manual inspector test
+python tests/test_inspector.py
 
-The assistant supports two templates with unified codebase:
+# Type checking
+make type-check
 
-- **Default Template**: Full project management with goals, criteria, and progress tracking
-- **Context Transfer Template**: Simplified knowledge sharing without formal project stages
-
-### Key Artifacts
-
-- **Project Brief**: Knowledge goals and success criteria
-- **Knowledge Digest**: Dynamically updated context repository (auto-generated from conversations)
-- **Learning Objectives**: Structured goals with specific learning outcomes
-- **Information Requests**: Bidirectional communication between coordinators and team members
-- **Inspector Panels**: Real-time multi-panel dashboard showing project state
+# Code quality
+make lint
+make format
+```
 
+### Assistant Management
+```bash
+# Start assistant service
+make start
 
-### Dependencies
+# Docker operations
+make docker-build
+make docker-run-local
+```
 
-The assistant uses several key dependencies from the Semantic Workbench ecosystem:
+## Project Structure
+
+### Core Implementation (`/assistant/`)
+- `assistant.py`: Main assistant with dual-role event handling
+- `config.py`: Role-specific prompt templates and configuration
+- `storage.py` & `storage_models.py`: Persistent state management
+- `conversation_share_link.py`: Cross-conversation linking and synchronization
+- `files.py`: File synchronization via ShareFilesManager
+- `respond.py`: Response generation logic
+- `common.py`: Role detection and common utilities
+
+### Agentic (`/assistant/agentic/`)
+- `team_welcome.py`: Team welcome message generation
+- `coordinator_support.py`: Coordinator guidance and support
+- `analysis.py`: Analysis functionality
+
+### Domain Logic (`/assistant/domain/`)
+- `share_manager.py`: Share creation, joining, and cross-conversation coordination (`ShareManager` class)
+- `knowledge_brief_manager.py`: Brief creation and management (`KnowledgeBriefManager` class)
+- `knowledge_digest_manager.py`: Auto-updating digest system (`KnowledgeDigestManager` class)
+- `learning_objectives_manager.py`: Learning goal tracking (`LearningObjectivesManager` class)
+- `information_request_manager.py`: Team question handling (`InformationRequestManager` class)
+- `audience_manager.py`: Audience definition and management (`AudienceManager` class)
+
+### Tools (`/assistant/tools/`)
+- `information_requests.py`: Information request handling
+- `learning_objectives.py`: Learning objective management
+- `learning_outcomes.py`: Outcome tracking
+- `progress_tracking.py`: Transfer progress monitoring
+- `share_setup.py`: Share link creation
+
+### UI Tabs (`/assistant/ui-tabs/`)
+- `brief.py`: Knowledge transfer status dashboard
+- `learning.py`: Learning objectives tracking
+- `sharing.py`: Sharing status monitoring
+- `debug.py`: Debug information panel
+
+### Configuration (`/assistant/text_includes/`)
+Role-specific prompts and instruction templates:
+- `coordinator_role.txt` & `coordinator_instructions.txt`: Coordinator mode configuration
+- `team_role.txt` & `team_instructions.txt`: Team mode configuration
+- `knowledge_digest_prompt.txt`: LLM prompts for digest generation
+
+## Key Dependencies
 
 - `semantic-workbench-assistant`: Core assistant framework
-- `assistant-extensions[attachments]`: File attachment support with dashboard cards and navigation
+- `assistant-extensions[attachments]`: File attachment support with dashboard cards
 - `content-safety`: Content moderation capabilities
 - `openai-client`: LLM integration for knowledge digest generation
-- `openai>=1.61.0`: Direct OpenAI API integration
-
-### Project Structure
-
-Key architectural files:
-- `/assistant/`: Core implementation files
-  - `assistant.py`: Main assistant with dual-role event handling
-  - `manager.py`: Project state and artifact management (KnowledgeTransferManager)
-  - `conversation_share_link.py`: Cross-conversation linking and synchronization
-  - `notifications.py`: Cross-conversation notification and UI refresh system
-  - `data.py`: Core data models and enums (InspectorTab, RequestPriority, etc.)
-  - `inspectors/`: Modular inspector panel system
-    - `brief.py`: Brief inspector for knowledge transfer status
-    - `learning.py`: Learning objectives inspector
-    - `sharing.py`: Sharing status inspector
-    - `debug.py`: Debug inspector
-    - `common.py`: Common inspector utilities
-  - `storage.py` & `storage_models.py`: Persistent state management
-  - `config.py`: Role-specific prompt templates and configuration
-  - `text_includes/`: Role-specific prompts and instruction templates
-  - `assets/`: SVG icons and visual assets
-- `/docs/`: Design documentation including `DESIGN.md`, `DEV_GUIDE.md`, `JTBD.md`, and `WORKBENCH_NOTES.md`
-- `/tests/`: Comprehensive test suite with manual inspector testing support
-
-## Code Style
-
-### Python
-
-- Indentation: 4 spaces
-- Line length: 120 characters
-- Imports: stdlib → third-party → local, alphabetized within groups
-- Naming: `snake_case` for functions/variables, `CamelCase` for classes, `UPPER_SNAKE_CASE` for constants
-- Types: Use type annotations consistently; prefer Union syntax (`str | None`) for Python 3.10+
-- Documentation: Triple-quote docstrings with param/return descriptions
-
-## Tools
-
-- Python: Uses uv for environment/dependency management
-- Linting/Formatting: Ruff (Python)
-- Type checking: Pyright (Python)
-- Testing: pytest (Python)
-- Package management: uv (Python)
 
-## Testing
-
-The assistant includes comprehensive test coverage:
-- `test_artifact_loading.py`: Artifact loading and management tests
-- `test_inspector.py`: State inspector functionality tests (can be run manually with `python tests/test_inspector.py`)
-- `test_share_manager.py`: File sharing and synchronization tests
-- `test_share_storage.py`: Storage system tests
-- `test_share_tools.py`: Tool functionality tests
-- `test_team_mode.py`: Team mode operation tests
-
-## Philosophy
+## Development Guidelines
 
-The codebase follows a **wabi-sabi philosophy** emphasizing:
+### Code Philosophy
+The project follows a "wabi-sabi" philosophy emphasizing:
 - Ruthless simplicity with minimal abstractions
 - Present-moment focus rather than future-proofing
 - Trust in emergence from simple, well-defined components
 - Direct library integration with minimal wrappers
-- Pragmatic trust in external systems
+
+### Code Style
+- Use 4 spaces for indentation
+- Maximum line length: 120 characters
+- Follow PEP 8 naming conventions
+- Use type annotations consistently
+- Write docstrings for functions and classes
+
+### Quality Assurance
+Always run the full quality check before submitting changes:
+```bash
+make lint && make type-check && make test
+```
+
+### Important Development Notes
+- Use `uv` for all Python script execution to ensure correct environment
+- Keep ConversationRole enum consistent across all files
+- Use Optional typing for parameters that might be None
+- Update tests when changing functionality - never skip or remove tests
+- Access logs in `.data/logs/` directory (timestamped, latest sorted last)
+- Never make git commits - leave that to QA review process
+
+## Testing
+
+The test suite covers:
+- Artifact loading and management (`test_artifact_loading.py`)
+- Inspector functionality (`test_inspector.py`)
+- File sharing and synchronization (`test_share_manager.py`)
+- Storage system operations (`test_share_storage.py`)
+- Tool functionality (`test_share_tools.py`)
+- Team mode operations (`test_team_mode.py`)
+
+Run tests with:
+```bash
+# All tests
+make test
+
+# Specific test file
+uv run pytest tests/test_share_manager.py -v
+
+# Single test function
+uv run pytest tests/test_share_manager.py::test_file_sync -v
+```

assistants/knowledge-transfer-assistant/assistant/agentic/__init__.py

@@ -12,8 +12,8 @@
 from openai.types.chat import ChatCompletionMessageParam
 from semantic_workbench_assistant.assistant_app import ConversationContext
 
-from .config import assistant_config
-from .logging import logger
+from ..config import assistant_config
+from ..logging import logger
 
 
 async def detect_information_request_needs(context: ConversationContext, message: str) -> Dict[str, Any]:

…transfer-assistant/assistant/analysis.py …-assistant/assistant/agentic/analysis.pyassistants/knowledge-transfer-assistant/assistant/analysis.py renamed to assistants/knowledge-transfer-assistant/assistant/agentic/analysis.py assistants/knowledge-transfer-assistant/assistant/analysis.py renamed to assistants/knowledge-transfer-assistant/assistant/agentic/analysis.py

@@ -11,6 +11,7 @@
 from ..data import RequestStatus
 from ..logging import logger
 from ..storage import ShareStorage
+from ..domain.share_manager import ShareManager
 
 
 class CoordinatorSupport:
@@ -28,9 +29,7 @@ async def get_coordinator_next_action_suggestion(context: ConversationContext) -
             A user-facing suggestion string, or None if no suggestion is needed.
         """
         try:
-            from .share_management import ShareManagement
-            
-            share_id = await ShareManagement.get_share_id(context)
+            share_id = await ShareManager.get_share_id(context)
             if not share_id:
                 logger.warning("No share ID found for this conversation")
                 return None
@@ -91,4 +90,4 @@ async def get_coordinator_next_action_suggestion(context: ConversationContext) -
 
         except Exception as e:
             logger.exception(f"Error generating next action suggestion: {e}")
-            return None
+            return None

…assistant/manager/coordinator_support.py …assistant/agentic/coordinator_support.pyassistants/knowledge-transfer-assistant/assistant/manager/coordinator_support.py renamed to assistants/knowledge-transfer-assistant/assistant/agentic/coordinator_support.py assistants/knowledge-transfer-assistant/assistant/manager/coordinator_support.py renamed to assistants/knowledge-transfer-assistant/assistant/agentic/coordinator_support.py

@@ -12,11 +12,11 @@
 from openai.types.chat import ChatCompletionMessageParam
 from semantic_workbench_assistant.assistant_app import ConversationContext
 
-from assistant.manager import KnowledgeTransferManager
+from assistant.domain import KnowledgeTransferManager
 from assistant.storage import ShareStorage
 
-from .config import assistant_config
-from .logging import logger
+from ..config import assistant_config
+from ..logging import logger
 
 
 async def generate_team_welcome_message(context: ConversationContext) -> tuple[str, dict[str, Any]]: