Skip to content

04 configuration initial setup

Jump to bottom
Doug Beard edited this page Aug 21, 2025 · 3 revisions

APM Initial Setup Configuration Guide

This guide walks you through the complete first-time configuration of the Agentic Persona Mapping (APM) framework.

Prerequisites

Before starting configuration:

  • APM framework installed via ./install.sh
  • Claude Code CLI installed and configured
  • Project directory structure in place
  • Basic understanding of APM concepts

Step 1: Core Configuration Files

1.1 Settings Configuration

Create or verify {{APM_ROOT}}/settings.json:

{
  "apm": {
    "version": "4.0.0",
    "root_path": "{{APM_ROOT}}",
    "project_root": "{{PROJECT_ROOT}}",
    "installer_root": "{{INSTALLER_ROOT}}"
  },
  "session_management": {
    "auto_create_notes": true,
    "session_timeout_hours": 8,
    "auto_archive_days": 7,
    "max_session_size_mb": 10
  },
  "voice_notifications": {
    "enabled": true,
    "voice_script_path": "{{APM_ROOT}}/agents/voice/",
    "audio_enabled": true,
    "notification_level": "standard"
  },
  "personas": {
    "master_definitions_path": "{{INSTALLER_ROOT}}/personas/_master/",
    "generated_templates_path": "{{APM_ROOT}}/agents/personas/",
    "auto_regenerate": true
  },
  "parallel_execution": {
    "native_subagents_enabled": true,
    "max_concurrent_agents": 4,
    "coordination_timeout_seconds": 300
  }
}

1.4 Environment Variables (Optional)

Set environment variables for customization:

# TTS Configuration
export TTS_PROVIDER="system"  # system, piper, elevenlabs, discord, none
export TTS_VOICE_SPEED="1.0"
export TTS_VOICE_VOLUME="0.8"

# Voice Notifications
export VOICE_NOTIFICATIONS_ENABLED="true"

# Debug Settings
export APM_DEBUG="false"

Step 2: Persona Configuration

2.1 Verify Persona Commands

Check that persona commands were installed:

ls -la .claude/commands/

Expected files:

  • coherence.md - Main orchestrator command
  • analyst.md - Business Analyst persona
  • architect.md - System Architect persona
  • developer.md - Developer persona
  • pm.md - Project Manager persona
  • po.md - Product Owner persona
  • qa.md - Quality Assurance persona
  • sm.md - Scrum Master persona

2.2 Test Persona Activation

Test that personas activate properly:

# In Claude Code, test primary command:
coherence

# Test individual personas:
/analyst
/developer
/architect

2.3 Customize Personas (Optional)

Edit persona command files to customize behavior:

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

# Edit specific personas
nano .claude/commands/developer.md
nano .claude/commands/architect.md

Step 3: Voice Notifications Setup

3.1 Verify Voice Scripts

Check voice script installation:

ls -la .apm/agents/voice/

Expected scripts:

  • speakBase.sh - Base voice functionality
  • speakOrchestrator.sh
  • speakDeveloper.sh
  • speakArchitect.sh
  • speakAnalyst.sh
  • speakQa.sh
  • speakPm.sh
  • speakPo.sh
  • speakSm.sh
  • speakDesignArchitect.sh

3.2 Test Voice Notifications

# Test orchestrator voice
.apm/agents/voice/speakOrchestrator.sh "APM configuration test successful"

# Test other personas
.apm/agents/voice/speakDeveloper.sh "Developer voice test"
.apm/agents/voice/speakArchitect.sh "Architect voice test"

# Test TTS system
.apm/agents/scripts/tts-manager.sh test

3.3 Configure TTS Providers

Check available TTS providers:

ls -la .apm/agents/scripts/tts-providers/

Available providers:

  • system.sh - System default TTS (macOS say, Linux espeak)
  • piper.sh - Piper neural TTS
  • elevenlabs.sh - ElevenLabs cloud TTS
  • discord.sh - Discord TTS integration
  • none.sh - Disable TTS

Configure provider:

# Set TTS provider
.apm/agents/scripts/configure-tts.sh

# Or set directly
export TTS_PROVIDER="system"

Step 4: Session Management Setup

4.1 Initialize Session Directories (Optional)

# Create session management structure if needed
mkdir -p .apm/session_notes
mkdir -p .apm/session_notes/archive
mkdir -p .apm/rules

# Set appropriate permissions
chmod 755 .apm/session_notes
chmod 755 .apm/session_notes/archive
chmod 755 .apm/rules

4.2 Create Default Rules

Create .apm/rules/default-behavior.md:

# APM Default Behavior Rules

## Session Management
- Always create session notes when activating personas
- Update session notes every 10-15 minutes during active work
- Archive sessions when wrapping or ending work
- Maintain context continuity between sessions

## Voice Notifications
- Use voice scripts for all persona responses
- Announce persona activation and major state changes
- Provide audio feedback for task completion
- Alert on errors or blocking issues

## Parallel Execution
- Use native sub-agents for parallel commands
- Coordinate between concurrent execution streams
- Aggregate results from parallel operations
- Monitor performance and resource usage

## Project Management
- Update backlog.md after any story-related work
- Track acceptance criteria completion
- Maintain sprint progress visibility
- Document decisions and architectural choices

4.3 Configure Session Templates

Create session note template at {{APM_ROOT}}/templates/session-note-template.md:

# Session: {{SESSION_TITLE}}
Date: {{SESSION_DATE}}
Persona: {{PERSONA_NAME}}
Previous Session: {{PREVIOUS_SESSION_LINK}}

## Objectives
- [ ] {{OBJECTIVE_1}}
- [ ] {{OBJECTIVE_2}}

## Context
{{SESSION_CONTEXT}}

## Progress
{{TIMESTAMP}} - Session initialized

## Decisions Made
- None yet

## Issues Encountered
- None yet

## Next Steps
- Continue with planned objectives
- Update session notes regularly
- Archive when complete

## Handoff Notes
{{HANDOFF_CONTEXT}}

Step 5: Development Integration

5.1 MCP Plopdock Configuration

Enable MCP Plopdock integration in settings:

{
  "development": {
    "mcp_debug_host_enabled": true,
    "debug_host_port": 8080,
    "auto_detect_servers": true,
    "persistent_servers": true,
    "voice_notifications_for_servers": true
  }
}

5.2 Claude Code Integration

Verify Claude Code configuration in {{PROJECT_ROOT}}/.claude/settings.json:

{
  "apm": {
    "enabled": true,
    "root": "{{APM_ROOT}}",
    "auto_activate": false
  },
  "hooks": {
    "pre_tool_use": "{{APM_ROOT}}/hooks/pre_tool_use.py",
    "post_tool_use": "{{APM_ROOT}}/hooks/post_tool_use.py",
    "user_prompt_submit": "{{APM_ROOT}}/hooks/user_prompt_submit.py"
  }
}

Step 6: Validation and Testing

6.1 Basic Functionality Test

Test core APM functionality:

# In Claude Code, run these commands one by one:
# /coherence
# /handoff dev
# /wrap

6.2 Persona Activation Test

Test each persona:

# Test commands (run in Claude Code):
# /analyst
# /architect
# /developer
# /pm
# /qa

6.3 Parallel Execution Test

Test native sub-agent parallelism:

# Test parallel command (run in Claude Code):
# /implementation-sprint

6.4 Voice Notification Test

Verify voice notifications work across personas:

# Manual voice tests
{{APM_ROOT}}/agents/voice/speakOrchestrator.sh "Orchestrator test"
{{APM_ROOT}}/agents/voice/speakDeveloper.sh "Developer test"
{{APM_ROOT}}/agents/voice/speakArchitect.sh "Architect test"

Step 7: Customization Options

7.1 Project-Specific Configuration

Create project-specific settings overlay:

{
  "project_specific": {
    "project_name": "{{PROJECT_NAME}}",
    "project_type": "web_application",
    "technology_stack": ["React", "Node.js", "MongoDB"],
    "team_size": 5,
    "sprint_length_weeks": 2
  },
  "custom_personas": {
    "enabled": false,
    "definitions_path": "{{PROJECT_ROOT}}/.apm/custom-personas/"
  }
}

7.2 Team Configuration

For team environments, create shared configuration:

{
  "team": {
    "shared_session_notes": true,
    "collaborative_backlog": true,
    "standardized_personas": true,
    "voice_notifications_team_wide": false
  }
}

Troubleshooting Initial Setup

Common Issues

Issue: native Claude Code slash commands not recognized

Solution:

  • Verify {{APM_ROOT}}/CLAUDE.md exists
  • Check Claude Code is reading project CLAUDE.md
  • Restart Claude Code session

Issue: Voice notifications not working

Solution:

  • Check audio system configuration
  • Verify voice script permissions: chmod +x {{APM_ROOT}}/agents/voice/*.sh
  • Test system audio: say "test" || espeak "test"

Issue: Persona templates not found

Solution:

  • Run persona generation: {{INSTALLER_ROOT}}/generate-personas.sh
  • Verify master definitions exist
  • Check file permissions

Issue: Session notes not saving

Solution:

  • Create session directories: mkdir -p {{APM_ROOT}}/session_notes
  • Check write permissions
  • Verify settings.json configuration

Next Steps

After completing initial setup:

  1. Read the Environment Variables Guide for advanced configuration
  2. Review the Persona Customization Guide to tailor behaviors
  3. Configure Voice Notifications for optimal audio feedback
  4. Set up Path Configuration for team environments

Configuration Complete

Your APM framework is now configured and ready for use. Test with:

/coherence

This should activate the Coherence Orchestrator with full voice notifications and session management.

Support: For configuration issues, check the troubleshooting section or review the detailed configuration guides in this directory.

Clone this wiki locally