Mentorship & Guidance Agents
Relevant source files
The following files were used as context for generating this wiki page:
Mentorship & Guidance Agents within the SuperAgent-MCP ecosystem are specialized personas designed to facilitate knowledge transfer, discovery learning, and technical communication. Unlike standard task-execution agents, these personas focus on the "why" behind technical decisions, guiding users through progressive learning paths and structured requirements discovery. They leverage specific pedagogical strategies, such as the Socratic method, to build user competence rather than simply providing direct answers.
These agents are managed as Markdown files with YAML frontmatter, allowing the agentLoader.ts to dynamically register them as tools within the MCP server. This architecture enables the server to provide distinct behavioral mindsets—ranging from the strict "precision and restraint" of a general-purpose investigator to the "question-based learning" of a mentor—depending on the user's specific instructional or research needs.
Sources: agents/socratic-mentor.md, agents/learning-guide.md, src/agentLoader.ts:88-118
Core Agent Personas
The system includes several specialized agents focused on communication, education, and analysis. Each is defined by specific "triggers" that activate their unique behavioral mindsets.
Socratic Mentor
The Socratic Mentor is the primary educational guide, prioritizing discovery learning over knowledge transfer. It follows a strict hierarchy where guiding the user to a solution is more important than providing the solution itself. It is deeply integrated with industry standard knowledge bases, specifically Robert C. Martin's Clean Code and the GoF Design Patterns.
Sources: agents/socratic-mentor.md:8-15
Learning Guide
The Learning Guide focuses on breaking down complex programming concepts into digestible steps. Its behavioral mindset is centered on teaching understanding rather than memorization, connecting new information to existing knowledge through practical, working examples.
Sources: agents/learning-guide.md:12-14
Technical Writer & Requirements Analyst
While the Technical Writer focuses on the usability and accessibility of documentation for specific audiences, the Requirements Analyst utilizes Socratic questioning to uncover true user needs before implementation begins. Both serve as bridges between complex technical logic and clear, actionable communication.
Sources: agents/technical-writer.md:12-14, agents/requirements-analyst.md:12-14
Behavioral Logic and Strategy
The following diagram illustrates the workflow of a Mentorship Agent when engaging with a user, specifically highlighting the "Discovery" vs. "Implementation" paths.
The workflow ensures that agents do not just execute tasks but adapt their communication style to the user's expertise and the specific category of the task.
Sources: agents/socratic-mentor.md:54-72, agents/learning-guide.md:23-28, agents/technical-writer.md:23-27
Specialized Methodologies
| Agent | Methodology | Primary Focus | Key Citations/Standards |
|---|---|---|---|
| Socratic Mentor | Question-Based Learning | Incremental principle mastery | Clean Code (Martin), GoF Patterns |
| Learning Guide | Progressive Learning | Step-by-step skill building | Educational Assessment |
| General-Purpose | Systematic Exploration | Precision and restraint | Git/File System Standards |
| Technical Writer | Audience-Centric Design | Usability and accessibility | WCAG 2.1 Compliance |
| Requirements Analyst | Systematic Discovery | Requirement clarification | PRD / User Story standards |
Sources: agents/socratic-mentor.md:17-48, agents/learning-guide.md:16-21, agents/general-purpose.md:14-17, agents/technical-writer.md:16-21, agents/requirements-analyst.md:16-21
Discovery Patterns in Socratic Mentorship
The Socratic Mentor uses specific YAML-defined patterns to guide discovery. For example, in "Naming Discovery," it follows a sequence of observation, pattern identification, and finally validation against established principles.
naming_discovery:
observation_question: "What do you notice when you first read this variable name?"
pattern_question: "How long did it take you to understand what this represents?"
principle_question: "What would make the name more immediately clear?"
validation: "This connects to Martin's principle about intention-revealing names..."
Sources: agents/socratic-mentor.md:27-32
System Architecture & Orchestration
Mentorship agents are integrated into the SuperAgent framework through a collaboration pattern. This allows an "Analyzer" or "Architect" persona to identify a problem and then "handoff" the interaction to a Mentorship agent for educational resolution.
This multi-persona coordination ensures that the technical depth of the project is used as a live learning environment.
Sources: agents/socratic-mentor.md:139-165
Technical Integration (agentLoader.ts)
Agents are loaded from ~/.superagent/agents by the agentLoader.ts module. The module parses the Markdown files to extract the system prompt, name, and category.
// src/agentLoader.ts:88-118
function parseAgentFile(content: string): Agent | null {
try {
const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
if (!frontmatterMatch) return null;
const frontmatter = frontmatterMatch[1];
const body = frontmatterMatch[2].trim();
const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
const descriptionMatch = frontmatter.match(/^description:\s*(.+)$/m);
return {
name: nameMatch[1].trim(),
description: descriptionMatch[1].trim(),
systemPrompt: body
};
} catch (error) {
return null;
}
}
Sources: src/agentLoader.ts:88-118
Conclusion
Mentorship & Guidance Agents transform the SuperAgent-MCP from a simple tool executor into a collaborative educational environment. By leveraging structured methodologies like the Socratic method and adhering to industry standards (Clean Code, WCAG), these agents ensure that users not only complete their tasks but also improve their underlying technical knowledge and communication clarity.