04 configuration customizing personas

APM Persona Customization Guide

This guide explains how to modify existing personas and create new ones in the Agentic Persona Mapping (APM) framework.

Persona Architecture Overview

APM v4.0.0 uses a unified persona system with single-source definitions:

• Master Definitions: JSON files in {{INSTALLER_ROOT}}/personas/_master/
• Template Generation: Automated generation to multiple output formats
• Native Execution: All personas use native sub-agent architecture

Persona Definition Flow

Master JSON Definition → Template Generator → Generated Templates → Runtime Execution
     ↓                        ↓                    ↓                   ↓
*.persona.json         generate-personas.sh    Multiple formats    Native sub-agents

Master Persona Definitions

Location and Structure

Master persona definitions are stored in: {{INSTALLER_ROOT}}/personas/_master/

Each persona has a corresponding JSON file:

• orchestrator.persona.json - Coherence Orchestrator
• analyst.persona.json - Business Analyst
• architect.persona.json - System Architect
• design-architect.persona.json - Design Architect
• developer.persona.json - Software Developer
• pm.persona.json - Project Manager
• po.persona.json - Product Owner
• qa.persona.json - Quality Assurance
• sm.persona.json - Scrum Master

Persona JSON Schema

{
  "persona": {
    "name": "PersonaName",
    "role": "Role Description",
    "version": "4.0.0",
    "description": "Comprehensive description of the persona",
    "created_date": "2025-01-15",
    "updated_date": "2025-01-15"
  },
  "behavior": {
    "core_responsibilities": [
      "Primary responsibility",
      "Secondary responsibility"
    ],
    "interaction_style": "Communication style description",
    "decision_making": "Decision making approach",
    "problem_solving": "Problem solving methodology",
    "collaboration": "How this persona collaborates with others"
  },
  "capabilities": {
    "primary_skills": [
      "Skill 1",
      "Skill 2"
    ],
    "tools_and_methods": [
      "Tool 1",
      "Method 1"
    ],
    "specializations": [
      "Specialization 1",
      "Specialization 2"
    ],
    "deliverables": [
      "Deliverable 1",
      "Deliverable 2"
    ]
  },
  "voice_characteristics": {
    "communication_style": "Professional tone description",
    "greeting_style": "How the persona greets users",
    "status_reporting": "How the persona reports status",
    "error_handling": "How the persona handles errors",
    "handoff_protocol": "How the persona hands off to others"
  },
  "session_management": {
    "activation_behavior": "What happens when persona activates",
    "session_initialization": "How sessions are initialized",
    "progress_tracking": "How progress is tracked",
    "completion_criteria": "When work is considered complete",
    "archival_process": "How sessions are archived"
  },
  "parallel_execution": {
    "supports_parallel": true,
    "max_concurrent_tasks": 4,
    "coordination_required": true,
    "resource_requirements": "Memory and processing requirements",
    "conflict_resolution": "How conflicts with parallel execution are resolved"
## Customizing Personas

### Method 1: Edit Command Files

Directly edit persona command files:

```bash
# Edit the developer persona
nano .claude/commands/developer.md

# Edit the architect persona
nano .claude/commands/architect.md

# Edit the main orchestrator
nano .claude/commands/coherence.md

Method 2: Customize Voice Messages

Edit voice scripts to customize audio notifications:

# Edit voice scripts
nano .apm/agents/voice/speakDeveloper.sh
nano .apm/agents/voice/speakArchitect.sh

# Test voice customizations
.apm/agents/voice/speakDeveloper.sh "Custom message test"

Example: Customizing the Developer Persona

Current Developer Command

# View current developer persona
cat .claude/commands/developer.md

Customizing Developer Behavior

# Edit developer persona file
nano .claude/commands/developer.md

Add custom behavior sections:

## Custom Developer Guidelines

### Code Quality Standards
- Always write comprehensive tests
- Follow project coding standards
- Use descriptive variable names
- Add inline documentation

### Technology Preferences
- Prefer TypeScript over JavaScript
- Use React for frontend development
- Implement RESTful API design
- Follow microservices architecture

### Voice Notifications
Triggers enhanced notifications with custom messages.

Testing Customizations

# Test the customized persona
# In Claude Code, run:
/developer

# Verify voice notification works
.apm/agents/voice/speakDeveloper.sh "Custom developer persona activated"

Best Practices for Persona Customization

1. Keep It Simple

• Focus on essential behavior changes
• Avoid overly complex instructions
• Test changes incrementally

2. Maintain Consistency

• Keep similar format across personas
• Use consistent terminology
• Align with project standards

3. Voice Integration

• Customize voice messages for persona personality
• Test voice scripts after changes
• Ensure TTS provider compatibility

4. Project-Specific Adaptations

• Add project context to persona instructions
• Include relevant technology stack information
• Customize based on team preferences

Advanced Customization

Project-Specific Personas

Create project-specific variations by modifying CLAUDE.md:

# Add to CLAUDE.md

## Project-Specific Developer Context
- Project uses Next.js and TypeScript
- Database: PostgreSQL with Prisma ORM
- Testing: Jest and React Testing Library
- Deployment: Vercel

Team Customizations

Standardize persona behavior across team:

# Share customized persona files
git add .claude/commands/
git commit -m "Customize APM personas for team standards"
git push

Troubleshooting Customizations

Issue: Persona not behaving as expected

# Check persona command file syntax
cat .claude/commands/developer.md

# Verify Claude Code reads the file
ls -la .claude/commands/

Issue: Voice notifications not reflecting changes

# Check voice script exists
ls -la .apm/agents/voice/speakDeveloper.sh

# Test voice script directly
.apm/agents/voice/speakDeveloper.sh "Test message"

Issue: Changes not taking effect

# Restart Claude Code session
# Re-activate persona:
/developer

---

Note: Persona customizations are project-specific and stored in your .claude/commands/ directory. Team members will need to share these files to maintain consistency.