Guides and Specialists Implementation

Overview

This document describes the implementation of the Guides and Specialists system in Sasha Studio, which allows users to apply contextual intelligence and specialized knowledge to their conversations.

System Architecture

Specialists

Specialists are persistent AI personalities that shape how Sasha responds throughout a conversation. They provide specialized expertise and communication styles.

• Default Specialist: General Sasha - comprehensive knowledge with balanced approach
• Persistence: Remains active across messages until changed
• Storage: Saved in localStorage for session persistence
• Visual Indicator: Blue badge in chat header

Guides

Guides are one-time contextual frameworks that provide structured approaches to specific tasks or analyses.

• Usage: Applied to enhance the current conversation
• Persistence: Automatically cleared after sending a message
• Visual Indicator: Individual green badges for each active guide
• Multiple Guides: Can apply multiple guides simultaneously

Implementation Details

File Structure

src/
├── components/
│   ├── PersonasPanel.jsx      # Specialist selection interface
│   ├── GuidesPanel.jsx         # Guide library interface
│   ├── ChatInterface.jsx       # Displays badges and system messages
│   └── MainContent.jsx         # Manages panel states
├── App.jsx                     # State management and context injection
└── server/
    └── services/
        └── content-reader.js   # Loads markdown content from filesystem

Content Loading

Content is loaded from markdown files in the following directories:

• System Personas: docs/private/personas/
• User Personas: docs/personas/
• System Guides: docs/private/guides/[category]/
• User Guides: docs/guides/[category]/

Data Flow

1. Selection Flow

User clicks persona/guide → Panel component → App.jsx handler → State update → UI refresh

2. Context Injection Flow

User sends message → ChatInterface includes context → WebSocket transmission → Server enhancement → Claude receives full context

Message Enhancement

When a message is sent with active context:

// Frontend (ChatInterface.jsx)
{
  message: "User's question",
  context: {
    persona: { id, name, content },
    guides: [{ id, title, content }, ...]
  }
}

// Server Enhancement (server/index.js)
"[Active Persona: Analyst Sasha]
{persona markdown content}

[Applied Guide: Competitor Analysis]
{guide markdown content}

[User Message]
User's question"

User Interface Features

Chat Header Badges

• Persona Badge (Blue):

  • Shows active persona name
  • X button to switch to General Sasha
  • Single badge since only one persona is active

• Guide Badges (Green):

  • Individual badge for each applied guide
  • Shows guide title (truncated if needed)
  • Individual X buttons to remove specific guides
  • Multiple badges can be displayed

System Messages

System messages appear in the chat history to track context changes:

• 📎 Applied persona: [Name] - When selecting a persona
• 📎 Switched to General Sasha - When clearing persona
• 📚 Applied guide: [Title] - When applying a guide
• 📚 Removed guide: [Title] - When removing a specific guide
• 📚 Cleared N guides - When clearing all guides

Panel Highlighting

• Personas Panel: Selected persona highlighted in blue
• Guides Panel: Active guides highlighted in green with "Active" label

Key Features

Default Persona System

• General Sasha loads as default on app start
• Clearing a persona switches to General Sasha (not null)
• Ensures consistent AI behavior at all times

Individual Guide Management

• Each guide displayed as separate removable badge
• Guides can be removed individually or all at once
• Visual feedback shows which guides are active

Visual Consistency

• Blue theme for personas (persistent context)
• Green theme for guides (temporary context)
• Consistent badge styling and interactions
• Responsive design for mobile devices

Technical Implementation

State Management (App.jsx)

const [activePersona, setActivePersona] = useState(null);
const [appliedGuides, setAppliedGuides] = useState([]);
const [defaultPersona, setDefaultPersona] = useState(null);

// Load General Sasha as default
useEffect(() => {
  loadDefaultPersona();
}, []);

// Handle guide removal (individual or all)
const clearAppliedGuides = (guideId) => {
  if (guideId) {
    // Remove specific guide
    setAppliedGuides(prev => prev.filter(g => g.id !== guideId));
  } else {
    // Clear all guides
    setAppliedGuides([]);
  }
};

Badge Rendering (ChatInterface.jsx)

// Individual guide badges
{appliedGuides.map((guide) => (
  <div key={guide.id} className="guide-badge">
    <BookOpen className="icon" />
    <span className="title">{guide.title}</span>
    <button onClick={() => onClearGuides(guide.id)}>
      <X className="close-icon" />
    </button>
  </div>
))}

Active Guide Highlighting (GuidesPanel.jsx)

const isActive = appliedGuides.some(g => g.id === guide.id);

<button className={isActive ? 'active-guide' : 'normal-guide'}>
  {isActive && <span className="active-label">Active</span>}
</button>

Benefits

1. Clear Visual Feedback: Users always know what context is active
2. Flexible Context Management: Mix and match personas and guides
3. Non-Intrusive: Context enhancement happens behind the scenes
4. Persistent Behavior: Personas maintain consistent AI behavior
5. Task-Specific Guidance: Guides provide structured approaches
6. Individual Control: Remove specific guides without clearing all

Future Enhancements

Potential improvements for future iterations:

• Guide categories with icons
• Custom persona creation interface
• Guide templates for common workflows
• Context preview before sending
• Guide combination recommendations
• Usage analytics for popular guides