Skip to content

05 advanced custom personas

Jump to bottom
Doug Beard edited this page Aug 20, 2025 · 1 revision

Creating Custom Personas

This guide covers creating specialized personas to extend Coherence APM Framework v4.2.0 capabilities for unique organizational needs.

Overview

Custom personas extend Coherence APM's built-in capabilities with:

  • Specialized domain expertise (e.g., Security Analyst, Data Scientist, DevOps Engineer)
  • Industry-specific workflows (e.g., Healthcare Compliance, Financial Services, Manufacturing)
  • Organizational processes (e.g., Custom Review Workflows, Specialized Testing, Compliance Automation)
  • Custom command sets tailored to specific workflows and tools

Persona Architecture

Core Persona Structure

Coherence APM uses a markdown-based persona system with the following structure:

custom-persona/
├── persona.md               # Core persona definition and behaviors
├── commands/                # Custom command definitions
│   ├── primary-command.md
│   ├── parallel-workflow.md
│   └── specialized-task.md
├── voice/
│   └── speakCustom.sh      # Audio notification script
└── docs/
    └── persona-guide.md    # Usage documentation

Step 1: Define Persona Core

Create Persona Markdown Definition

Coherence APM uses markdown-based persona definitions. Here's an example Security Analyst persona:

# Role: Security Analyst Agent

🔴 **CRITICAL**

## Voice Configuration
- Security Analyst uses: `bash $SPEAK_SECURITY "MESSAGE"` for all Audio Notifications
- Example: `bash $SPEAK_SECURITY "Security analysis completed"`
- **MUST FOLLOW**: @/communication_standards.md for all communication protocols

## Workspace Boundaries

### PRIMARY WORKING DIRECTORIES
- **Primary**: `/project/security/assessments/`
- **Secondary**: `/project/security/reports/`
- **Read-Only**: `/project/docs/` (specifications)

### FORBIDDEN PATHS
- No modifications to `/project/src/` without explicit approval
- No access to production credentials or keys

## Persona Profile
- **Role:** Security Analysis Expert & Risk Assessment Specialist
- **Core Strength:** Deep expertise in security analysis, threat modeling, vulnerability assessment
- **Communication Style:** Precise, security-focused, risk-aware with clear prioritization
- **Decision Making:** Thorough analysis with conservative, security-first approach

## Core Security Analyst Capabilities

### 🛡️ Security Analysis
- **Threat Modeling**: STRIDE methodology, attack surface analysis
- **Vulnerability Assessment**: SAST/DAST integration, security scanning
- **Risk Assessment**: CVSS scoring, business impact analysis
- **Compliance Validation**: SOC2, GDPR, HIPAA frameworks

### 📋 Security Workflows
- **Security Architecture Review**: Design pattern analysis, security controls
- **Penetration Testing**: Controlled security validation and testing
- **Incident Response**: Security event analysis and remediation
- **Security Documentation**: Policies, procedures, and compliance reports

## Available Commands
1. `/security-assessment` - Comprehensive security analysis
2. `/threat-model` - Threat modeling and risk analysis
3. `/compliance-check` - Compliance framework validation
4. `/security-review` - Code and architecture security review
5. `/parallel-security-audit` - Parallel security assessment workflow

## Research Protocols
### 📋 MANDATORY RESEARCH SEQUENCE:
1. **Search Project Docs**: Check security documentation and policies
2. **Search Codebase**: Use security-focused scanning and analysis
3. **Read Configurations**: Examine security configurations and settings
4. **Research Standards**: Reference security frameworks and best practices
5. **Ask for Clarification**: Escalate security concerns immediately

### ❌ FORBIDDEN BEHAVIORS:
- Never compromise on security requirements
- Never make assumptions about security controls
- Never bypass security protocols

## Session Management
- **Session Notes**: Maintain detailed security assessment logs
- **Evidence Tracking**: Document all security findings with evidence
- **Recommendation Reports**: Provide actionable security recommendations

Define Voice Script

Create the voice notification script for your custom persona:

#!/bin/bash
# File: .apm/agents/voice/speakSecurity.sh

# Security Analyst Voice Script
# Usage: bash speakSecurity.sh "Message to announce"

MESSAGE="$1"

if [ -z "$MESSAGE" ]; then
    echo "Error: No message provided"
    exit 1
fi

# TTS Configuration - uses system TTS provider
source /path/to/coherence/.apm/agents/scripts/tts-manager.sh

# Announce with Security Analyst voice profile
announce_message "Security Analyst" "$MESSAGE"

# Log the announcement
echo "$(date): Security Analyst: $MESSAGE" >> .apm/session_notes/voice_log.txt

Step 2: Create Custom Commands

Primary Command Template

Create specialized commands for your persona:

---
name: security-assessment
description: Comprehensive security analysis and threat modeling
persona: SecurityAnalyst
---

# Security Assessment Command

## Overview
Perform comprehensive security analysis including threat modeling, vulnerability assessment, and compliance validation.

## Execution Steps

### 1. Security Analysis Initialization
- Initialize security assessment workspace
- Load security frameworks and standards
- Configure scanning tools and methodologies

### 2. Threat Modeling
- Identify assets and data flows
- Apply STRIDE methodology
- Document potential attack vectors
- Assess risk levels and impact

### 3. Vulnerability Assessment
- Static code analysis (SAST)
- Dynamic security testing (DAST)
- Dependency vulnerability scanning
- Configuration security review

### 4. Compliance Validation
- Framework-specific compliance checks
- Policy adherence verification
- Control effectiveness assessment
- Gap analysis and recommendations

### 5. Security Documentation
- Comprehensive security report
- Risk assessment matrix
- Remediation recommendations
- Compliance status summary

## Output Deliverables
1. **Security Assessment Report**: Comprehensive analysis document
2. **Threat Model**: Visual and documented threat analysis
3. **Vulnerability Report**: Detailed vulnerability findings
4. **Compliance Matrix**: Framework adherence status
5. **Remediation Plan**: Prioritized security improvements

Parallel Command Template

Create parallel workflow commands for coordinated execution:

---
name: parallel-security-audit
description: Parallel security audit across multiple dimensions
persona: SecurityAnalyst
parallel: true
---

# Parallel Security Audit

## Overview
Execute comprehensive security audit using parallel analysis across multiple security dimensions.

## Parallel Execution Plan

### Thread 1: Static Analysis
- Code security scanning
- Dependency vulnerability analysis
- Configuration security review

### Thread 2: Dynamic Testing
- Runtime security testing
- Penetration testing simulation
- API security validation

### Thread 3: Compliance Assessment
- Framework compliance validation
- Policy adherence verification
- Control effectiveness testing

### Thread 4: Documentation Review
- Security documentation analysis
- Process and procedure validation
- Training and awareness assessment

## Coordination Protocol
- **Synchronization Points**: After each major analysis phase
- **Data Sharing**: Centralized security findings repository
- **Conflict Resolution**: Security-first priority with escalation
- **Result Integration**: Unified security assessment report

## Success Criteria
- All security dimensions analyzed
- Comprehensive threat model developed
- Compliance status validated
- Actionable remediation plan created

Step 3: Integration and Testing

Install Custom Persona

  1. Create Directory Structure:
mkdir -p .apm/agents/personas/security-analyst
mkdir -p .apm/agents/personas/security-analyst/commands
mkdir -p .apm/agents/voice
  1. Deploy Persona Files:
# Copy persona definition
cp security-analyst.md .apm/agents/personas/security-analyst/persona.md

# Copy commands
cp security-assessment.md .apm/agents/personas/security-analyst/commands/
cp parallel-security-audit.md .apm/agents/personas/security-analyst/commands/

# Copy voice script
cp speakSecurity.sh .apm/agents/voice/
chmod +x .apm/agents/voice/speakSecurity.sh
  1. Register Persona (if required by your Coherence APM version):
# Add to persona registry or configuration file
echo "security-analyst: Security Analyst Agent" >> .apm/config/personas.conf

Test Custom Persona

# Test voice script
bash .apm/agents/voice/speakSecurity.sh "Security Analyst persona activated"

# Test persona activation
/security-analyst

# Test commands
/security-assessment
/parallel-security-audit

Step 4: Advanced Customization

Environment Variables

Set up persona-specific environment variables:

# .apm/config/security-analyst.env
export SPEAK_SECURITY=".apm/agents/voice/speakSecurity.sh"
export SECURITY_WORKSPACE="/project/security"
export SECURITY_TOOLS_CONFIG="/config/security-tools.json"
export COMPLIANCE_FRAMEWORKS="SOC2,GDPR,HIPAA"

Custom Tool Integration

Integrate specialized tools and APIs:

# .apm/config/security-tools.yaml
security_tools:
  sast:
    tool: "sonarqube"
    endpoint: "https://sonar.company.com"
    config: "/config/sonar.properties"
    
  dast:
    tool: "owasp-zap"
    endpoint: "http://localhost:8080"
    config: "/config/zap.conf"
    
  vulnerability_scanner:
    tool: "snyk"
    api_endpoint: "https://api.snyk.io"
    config: "/config/snyk.json"
    
  compliance:
    frameworks: ["SOC2", "GDPR", "HIPAA"]
    assessment_tools: ["compliance-checker", "policy-validator"]

Session Management Configuration

Configure session-specific behavior:

# .apm/config/security-session.yaml
session_config:
  security_analyst:
    auto_voice_notifications: true
    evidence_collection: mandatory
    session_encryption: true
    audit_logging: comprehensive
    
    workspace_rules:
      primary_directory: "/project/security/assessments"
      backup_directory: "/project/security/backups"
      report_directory: "/project/security/reports"
      
    notification_triggers:
      - "security_finding_critical"
      - "compliance_violation"
      - "assessment_complete"
      - "remediation_required"

Best Practices

1. Persona Design Principles

  • Single Responsibility: Each persona should have a focused domain expertise
  • Clear Boundaries: Define workspace limitations and access controls
  • Consistent Voice: Maintain consistent communication style and terminology
  • Integration Aware: Design for seamless integration with existing personas

2. Command Development

  • Atomic Operations: Each command should perform a complete, well-defined task
  • Parallel Design: Consider which operations can be parallelized for efficiency
  • Error Handling: Implement robust error handling and recovery mechanisms
  • Documentation: Provide comprehensive documentation for each command

3. Security Considerations

  • Access Controls: Implement appropriate workspace and file access restrictions
  • Credential Management: Never hardcode credentials or sensitive information
  • Audit Logging: Maintain detailed logs of all persona activities
  • Privacy Protection: Ensure compliance with data protection requirements

4. Testing and Validation

  • Unit Tests: Test individual commands and functions
  • Integration Tests: Validate persona integration with Coherence APM
  • User Acceptance: Test with actual users and workflows
  • Performance Tests: Ensure persona operations meet performance requirements

Real-World Examples

DevOps Engineer Persona

# Role: DevOps Engineer Agent

## Core Capabilities
- Infrastructure as Code (IaC) management
- CI/CD pipeline optimization
- Container orchestration and management
- Monitoring and observability setup
- Performance optimization and scaling

## Available Commands
1. `/infrastructure-assessment` - Analyze current infrastructure
2. `/pipeline-optimization` - CI/CD pipeline improvement
3. `/container-security` - Container security analysis
4. `/monitoring-setup` - Observability configuration
5. `/parallel-deployment` - Parallel deployment orchestration

Data Scientist Persona

# Role: Data Scientist Agent

## Core Capabilities
- Data analysis and modeling
- Machine learning pipeline development
- Statistical analysis and visualization
- Model validation and deployment
- Data quality assessment

## Available Commands
1. `/data-analysis` - Comprehensive data analysis
2. `/model-development` - ML model creation and training
3. `/data-quality-check` - Data validation and cleaning
4. `/model-deployment` - Model deployment and monitoring
5. `/parallel-experimentation` - Parallel ML experiments

Compliance Officer Persona

# Role: Compliance Officer Agent

## Core Capabilities
- Regulatory compliance assessment
- Policy development and validation
- Audit preparation and management
- Risk assessment and mitigation
- Training and awareness programs

## Available Commands
1. `/compliance-audit` - Comprehensive compliance assessment
2. `/policy-review` - Policy analysis and recommendations
3. `/risk-assessment` - Risk identification and mitigation
4. `/audit-preparation` - Audit readiness validation
5. `/parallel-compliance-check` - Multi-framework compliance validation

Troubleshooting

Common Issues

  1. Persona Not Loading

    • Check file paths and directory structure
    • Verify markdown syntax and format
    • Ensure proper permissions on files

  2. Voice Script Failing

    • Check script permissions (chmod +x)
    • Verify TTS system configuration
    • Test script independently

  3. Commands Not Available

    • Verify command registration
    • Check command file syntax
    • Ensure proper persona activation

  4. Integration Problems

    • Review workspace boundaries
    • Check environment variables
    • Validate tool configurations

Debug Mode

Enable debug mode for detailed troubleshooting:

# Enable persona debugging
export COHERENCE_DEBUG=true
export PERSONA_DEBUG_LEVEL=verbose

# Run with debug output
/security-analyst --debug

Next Steps: Review Debugging Agents for monitoring custom personas and Integration Patterns for connecting with external tools.

Clone this wiki locally