Mentor Agent

The Mentor agent (MENTOR) is your orchestration specialist for complete feature implementation workflows. It guides you from initial feature requests through research integration, story creation, implementation coordination, and PR preparation.

Capabilities

• End-to-end feature orchestration from idea to merged PR
• Research integration from docs/10-research/
• Epic and story creation when needed
• Multi-agent coordination and status management
• CLAUDE.md maintenance and pattern documentation
• Slack command orchestration (41 available commands)
• Definition of Ready validation and gap filling
• Agent dependency resolution and WIP management

When to Use

Use the Mentor agent when:

• You have a plain-English feature request to implement
• You need to plan implementation across multiple stories/epics
• You need to research an unfamiliar technology before starting
• You're coordinating work between specialized agents (AG-UI, AG-API, AG-CI, AG-DEVOPS)
• You need to ensure Definition of Ready is met before implementation
• You want to automate PR generation and coordination

How It Works

1. Context Loading: Agent reads expertise file, status.json, bus/log.jsonl, and roadmap
2. Knowledge Analysis: Agent identifies current WIP, blockers, ready stories, and research gaps
3. Proposal: Agent suggests 3-7 prioritized next actions based on roadmap and dependencies
4. Planning: Agent creates missing epics/stories, ensures Definition of Ready is met
5. Research Integration: Agent leverages or requests research from docs/10-research/
6. Coordination: Agent orchestrates specialized agents and updates status/bus
7. Documentation: Agent updates CLAUDE.md with newly learned patterns
8. Finalization: Agent generates PR description and prepares for merge

Example

Copy# Via /babysit (recommended)
/agileflow:babysit
> "I need to add payment processing to the platform"

The Mentor will:

1. Check if payment epic exists; create if needed
2. Break into stories (setup, Stripe integration, webhook handling, etc.)
3. Research payment patterns (check docs/10-research/ or suggest new research)
4. Validate Definition of Ready for each story
5. Suggest which story to implement first
6. Coordinate implementation with specialized agents
7. Update status as work progresses

Or spawn directly:

CopyTask(
  description: "Implement user authentication",
  prompt: "Add JWT-based auth with login/logout flows, profile management",
  subagent_type: "agileflow-mentor"
)

Key Behaviors

• Autonomous Command Execution: Directly invokes slash commands (board, status, impact-analysis, research:ask, etc.) without asking permission
• Story Lifecycle Management: Validates Definition of Ready, marks in-progress, moves to in-review, updates to done
• WIP Limit Enforcement: Respects max 2 stories per agent in in-progress state
• Dependency Tracking: Identifies blockers, coordinates unblocking between agents
• Research-Driven Planning: Integrates existing research or requests new research via /agileflow:research:ask
• Proactive CLAUDE.md Updates: Documents new patterns/conventions discovered during implementation
• Cross-Agent Coordination: Uses bus/log.jsonl to message other agents (AG-UI, AG-API, AG-CI, AG-DEVOPS)
• Context Preservation: Uses compact_context (priority: critical) to maintain orchestration focus during long conversations, preserving Definition of Ready validation and blocker tracking through context compaction

Compact Context Configuration

The Mentor agent uses critical priority compact_context to ensure orchestration focus is never lost:

Copycompact_context:
  priority: critical
  preserve_rules:
    - "ALWAYS read expertise.yaml first"
    - "ALWAYS validate Definition of Ready before implementation"
    - "Max 2 stories per agent in-progress (WIP limit)"
    - "Slash commands are autonomous (invoke directly)"
    - "File operations require diff + YES/NO confirmation"
    - "Update status.json + bus/log.jsonl for all state changes"
  state_fields:
    - current_story
    - story_status
    - wip_count
    - blockers
    - next_actions

This ensures mentor-critical rules (Definition of Ready validation, WIP limits, autonomous command execution) and orchestration state (current story, blockers, prioritized next actions) are always preserved even after extensive context compaction.

Tools Available

This agent has access to: Read, Write, Edit, Bash, Glob, Grep

Bus Message Types

The Mentor communicates via these message types:

Copy{"ts":"2025-10-21T10:00:00Z","from":"MENTOR","type":"status","story":"<US-ID>","text":"Description"}
{"ts":"2025-10-21T10:00:00Z","from":"MENTOR","type":"blocked","story":"<US-ID>","text":"Blocked: <reason>"}
{"ts":"2025-10-21T10:00:00Z","from":"MENTOR","type":"unblock","story":"<US-ID>","text":"Unblocking: <reason>"}
{"ts":"2025-10-21T10:00:00Z","from":"MENTOR","type":"assign","story":"<US-ID>","text":"Assigned to <AGENT-ID>"}
{"ts":"2025-10-21T10:00:00Z","from":"MENTOR","type":"question","story":"<US-ID>","text":"Clarification needed: <question>"}

Key Files

• Expertise: packages/cli/src/core/experts/mentor/expertise.yaml (agent memory)
• Workflow: packages/cli/src/core/experts/mentor/workflow.md (Plan → Build → Self-Improve)
• Status: docs/09-agents/status.json (story tracking - single source of truth)
• Bus: docs/09-agents/bus/log.jsonl (coordination messages)
• Roadmap: docs/08-project/roadmap.md (priorities and context)
• Research: docs/10-research/ (technical research notes)
• ADRs: docs/03-decisions/ (architecture decisions)
• CLAUDE.md: Project-specific AI system prompt

Workflow Steps

1. Load Expertise: Read expertise.yaml to load mental model
2. Check Status: Read status.json for current WIP, blockers, ready stories
3. Read Bus: Check bus/log.jsonl for recent agent activity
4. Check Roadmap: Review docs/08-project/roadmap.md for priorities
5. Propose Actions: Suggest 3-7 next actions ranked by priority
6. Plan: Break feature into epics/stories with acceptance criteria
7. Research: Integrate existing research or suggest new research
8. Assign: Create stories with agent assignments and test stubs
9. Update Status: Mark stories as ready, update status.json
10. Message Bus: Append coordination messages
11. Implement: Guide implementation through specialized agents
12. Document: Update CLAUDE.md with new patterns
13. Generate PR: Use /agileflow:pr-template for PR description
14. Self-Improve: Run self-improve.md after completion

Agent Coordination

MENTOR coordinates with:

• AG-UI: Frontend stories - checks for blocked UI stories waiting on API
• AG-API: Backend stories - ensures API endpoints are ready to unblock UI
• AG-CI: Test infrastructure - coordinates test setup and verification
• AG-DEVOPS: Dependencies and deployment - coordinates migrations and package updates
• EPIC-PLANNER: Story decomposition - delegates epic/story planning when needed
• RESEARCH: Technical research - coordinates research on unfamiliar technologies

Related Agents

• epic-planner - Specialized in breaking features into epics and stories
• api - Backend services and data layer implementation
• ui - Frontend components and user interfaces