persona-setup

AI Persona OS Setup Wizard

This skill guides users through the first-run setup of AI Persona OS, creating a personalized workspace at ~/workspace with configured persona files.

Overview

The setup wizard:

1. Detects existing installations to avoid overwriting user data
2. Presents preset selection menu with 4 persona templates
3. Gathers personalization context through interactive questions
4. Builds workspace structure with appropriate templates and examples
5. Shows completion summary with optional advanced feature offers

Critical Rules

• NEVER tell the user to run commands — always use the Bash tool to execute commands directly
• NEVER modify existing workspace files without explicit user permission
• Only the 4 documented presets exist (coding-assistant, executive-assistant, marketing-assistant, custom)
• All operations are scoped to ~/workspace only
• Advanced features (cron, gateway, Discord) are opt-in mentions only, never pushed

Phase 1: Post-Install Detection

Step 1.1: Check for Existing Workspace

Use Bash tool to check if ~/workspace exists and contains core files:

if [ -d ~/workspace ]; then
  existing_files = []
  for file in SOUL.md USER.md MEMORY.md; do
    if [ -f ~/workspace/$file ]; then
      existing_files.append(file)
    fi
  done

  if existing_files.length > 0; then
    state.workspace_exists = true
    state.existing_files = existing_files
  fi
fi

Step 1.2: Handle Existing Installation

If state.workspace_exists == true, inform the user:

"I detected an existing AI Persona OS workspace at ~/workspace with these files: [list state.existing_files]. This setup wizard is for fresh installations. Would you like to:

• Skip setup and use your existing workspace
• Create a backup and reinitialize (will backup to ~/workspace.backup.TIMESTAMP)
• Cancel setup"

Based on response:

• Skip: Exit with success message
• Backup: Use Bash to run mv ~/workspace ~/workspace.backup.$(date +%Y%m%d_%H%M%S), then continue to Phase 2
• Cancel: Exit gracefully

If no existing workspace detected, proceed to Phase 2.

Phase 2: Preset Selection

Step 2.1: Display Preset Menu

Show the user this EXACT preset selection menu (verbatim):

Welcome to AI Persona OS Setup!

Please choose a preset to get started:

1. Coding Assistant
   - Helps with software development, debugging, code review
   - Proactive suggestions for testing, documentation, refactoring
   - Tracks projects, tasks, technical decisions

2. Executive Assistant
   - Manages schedule, meetings, email drafts
   - Proactive reminders, deadline tracking, priority management
   - Handles correspondence, reports, strategic planning support

3. Marketing Assistant
   - Content creation, campaign planning, analytics review
   - Proactive content ideas, publishing reminders, trend analysis
   - Social media management, SEO optimization, audience insights

4. Custom Persona
   - Define your own persona name, role, and behavior
   - Choose communication style and proactivity level
   - Full control over personality and capabilities

Which preset would you like? (1-4)

Step 2.2: Capture Preset Choice

Use AskUserQuestion to get the selection:

{
  "questions": [
    {
      "id": "preset_choice",
      "question": "Which preset would you like? (1-4)",
      "default": "1"
    }
  ]
}

Map the response:

• 1 → state.preset = "coding-assistant"
• 2 → state.preset = "executive-assistant"
• 3 → state.preset = "marketing-assistant"
• 4 → state.preset = "custom"
• Vague/unclear answer → state.preset = "coding-assistant" (default)

Store the preset in state.preset.

Phase 3: Gather Personalization Context

Step 3.1: Ask Common Questions (Presets 1-3)

For presets 1, 2, or 3, gather basic personalization:

{
  "questions": [
    {
      "id": "user_name",
      "question": "What's your name?",
      "default": "User"
    },
    {
      "id": "user_nickname",
      "question": "What should I call you? (nickname or preferred name)",
      "default": "<same as user_name>"
    },
    {
      "id": "user_role",
      "question": "What's your professional role or title?",
      "default": "Professional"
    },
    {
      "id": "user_goal",
      "question": "What's your main goal in using AI Persona OS?",
      "default": "Be more productive"
    }
  ]
}

Store responses in:

• state.user_name (default: "User")
• state.user_nickname (default: same as user_name)
• state.user_role (default: "Professional")
• state.user_goal (default: "Be more productive")

Set preset-specific defaults:

• state.persona_name = "Persona"
• state.persona_role = "personal assistant"
• state.comm_style = "c" (balanced)
• state.proactive_level = "b" (moderate)

Step 3.2: Ask Extended Questions (Preset 4 - Custom)

For preset 4 (custom), gather all personalization including persona configuration:

{
  "questions": [
    {
      "id": "user_name",
      "question": "What's your name?",
      "default": "User"
    },
    {
      "id": "user_nickname",
      "question": "What should I call you? (nickname or preferred name)",
      "default": "<same as user_name>"
    },
    {
      "id": "user_role",
      "question": "What's your professional role or title?",
      "default": "Professional"
    },
    {
      "id": "user_goal",
      "question": "What's your main goal in using AI Persona OS?",
      "default": "Be more productive"
    },
    {
      "id": "persona_name",
      "question": "What would you like to name your AI persona?",
      "default": "Persona"
    },
    {
      "id": "persona_role",
      "question": "What role should your persona play? (e.g., 'coding mentor', 'executive assistant', 'creative partner')",
      "default": "personal assistant"
    },
    {
      "id": "comm_style",
      "question": "Choose communication style:\n  a) Formal and professional\n  b) Friendly and casual\n  c) Balanced (professional but approachable)\n  d) Technical and precise\nYour choice (a-d)?",
      "default": "c"
    },
    {
      "id": "proactive_level",
      "question": "Choose proactivity level:\n  a) Reactive only (wait for requests)\n  b) Moderate (occasional suggestions)\n  c) Highly proactive (frequent suggestions and reminders)\nYour choice (a-c)?",
      "default": "b"
    }
  ]
}

Store all responses with the same defaults as Step 3.1, plus:

• state.persona_name (default: "Persona")
• state.persona_role (default: "personal assistant")
• state.comm_style (default: "c")
• state.proactive_level (default: "b")

Phase 4: Build Workspace Structure

Step 4.1: Create Directory Structure

Use Bash tool to create the workspace directory:

mkdir -p ~/workspace/memory
mkdir -p ~/workspace/projects
mkdir -p ~/workspace/context

Step 4.2: Copy Preset-Specific Starter Pack

Based on state.preset, copy the appropriate starter pack from plugin assets:

preset_examples = {
  "coding-assistant": "${CLAUDE_PLUGIN_ROOT}/examples/coding-assistant/",
  "executive-assistant": "${CLAUDE_PLUGIN_ROOT}/examples/executive-assistant/",
  "marketing-assistant": "${CLAUDE_PLUGIN_ROOT}/examples/marketing-assistant/",
  "custom": "${CLAUDE_PLUGIN_ROOT}/examples/custom/"
}

source_dir = preset_examples[state.preset]

# Copy all files from preset example directory to ~/workspace
cp -r ${source_dir}/* ~/workspace/

Use Bash tool to execute the copy operation.

Step 4.3: Copy Shared Templates

Copy shared template files that all presets need:

# Copy SOUL.md template
cp ${CLAUDE_PLUGIN_ROOT}/assets/SOUL.md.template ~/workspace/SOUL.md

# Copy MEMORY.md template
cp ${CLAUDE_PLUGIN_ROOT}/assets/MEMORY.md.template ~/workspace/MEMORY.md

Use Bash tool to execute these copy operations.

Step 4.4: Personalize Template Files

Use Bash tool with sed to personalize the copied templates:

# Personalize SOUL.md
sed -i 's/{{PERSONA_NAME}}/'"${state.persona_name}"'/g' ~/workspace/SOUL.md
sed -i 's/{{PERSONA_ROLE}}/'"${state.persona_role}"'/g' ~/workspace/SOUL.md
sed -i 's/{{COMM_STYLE}}/'"${state.comm_style}"'/g' ~/workspace/SOUL.md
sed -i 's/{{PROACTIVE_LEVEL}}/'"${state.proactive_level}"'/g' ~/workspace/SOUL.md

# Personalize MEMORY.md
sed -i 's/{{USER_NAME}}/'"${state.user_name}"'/g' ~/workspace/MEMORY.md
sed -i 's/{{USER_NICKNAME}}/'"${state.user_nickname}"'/g' ~/workspace/MEMORY.md

Execute all sed commands via Bash tool in a single call using && to chain them.

Step 4.5: Generate USER.md

Create USER.md using a heredoc with gathered information. Use Bash tool:

cat > ~/workspace/USER.md <<'EOF'
# User Profile

## Basic Information

**Name:** ${state.user_name}
**Preferred Name:** ${state.user_nickname}
**Role:** ${state.user_role}
**Primary Goal:** ${state.user_goal}

## Workspace Context

**Preset:** ${state.preset}
**Setup Date:** $(date +%Y-%m-%d)

## Preferences

Communication Style: See SOUL.md for persona configuration
Proactivity Level: See SOUL.md for persona configuration

## Active Projects

<!-- This section will be populated as you work -->

## Important Context

<!-- Add any context the AI should always remember -->

---

*This file was generated by the AI Persona OS setup wizard. Feel free to edit and expand it.*
EOF

Substitute the actual variable values before executing.

Phase 5: Show Setup Summary

Step 5.1: Verify Installation

Use Bash tool to list created files:

ls -la ~/workspace/
ls -la ~/workspace/memory/

Store the output in state.workspace_contents.

Step 5.2: Display Success Summary

Show the user a completion message with file checklist:

✓ AI Persona OS Setup Complete!

Your workspace has been created at ~/workspace with the following structure:

Core Files:
  ✓ SOUL.md       - Persona configuration and behavior
  ✓ USER.md       - Your profile and preferences
  ✓ MEMORY.md     - Persistent memory across sessions

Directories:
  ✓ memory/       - Session logs and historical context
  ✓ projects/     - Project-specific files and notes
  ✓ context/      - Additional context documents

Preset-Specific Files:
  [List any additional files from state.workspace_contents]

Your ${state.preset} persona is ready to use!

Next Steps:
1. Review and customize SOUL.md to fine-tune persona behavior
2. Update USER.md with any additional context
3. Start a new session — your persona will load automatically

Step 5.3: Offer Optional Advanced Features (Non-Pushy)

Mention advanced features as optional enhancements, never push:

"Optional advanced features you can explore later:

• Heartbeat monitoring: Periodic check-ins and progress tracking
• Cron integration: Scheduled tasks and automated workflows
• Team mode: Multi-user workspace support
• Discord integration: Notifications and remote interaction

These are completely optional. Your setup is fully functional as-is. Would you like to hear more about any of these features, or are you ready to start using your persona?"

Based on response:

• If user asks about a feature, provide brief explanation and mention it can be configured later
• If user is ready to start, end with: "Great! Your AI Persona OS is ready. Start a new session and your persona will load automatically from ~/workspace."

State Management

Track these variables throughout execution:

state.workspace_exists = false  # true if ~/workspace detected
state.existing_files = []       # list of existing core files
state.preset = ""               # selected preset slug
state.user_name = "User"
state.user_nickname = ""        # defaults to user_name
state.user_role = "Professional"
state.user_goal = "Be more productive"
state.persona_name = "Persona"
state.persona_role = "personal assistant"
state.comm_style = "c"          # a/b/c/d
state.proactive_level = "b"     # a/b/c
state.workspace_contents = ""   # ls output after creation

Error Handling

Missing Plugin Assets

If template files are not found at ${CLAUDE_PLUGIN_ROOT}/assets/ or ${CLAUDE_PLUGIN_ROOT}/examples/:

1. Use Glob to search for the plugin root
2. If still not found, inform user: "Setup wizard requires AI Persona OS plugin assets. Please ensure the plugin is properly installed."
3. Offer to continue with minimal setup (create directories and basic files without templates)

Permission Errors

If mkdir or cp commands fail with permission errors:

1. Show the error message to the user
2. Suggest checking directory permissions: "You may need write access to your home directory."
3. Offer alternative: "Would you like to specify a different workspace location?"

Invalid Preset Selection

If user provides input that doesn't map to 1-4:

1. Default to preset 1 (coding-assistant)
2. Inform user: "Defaulting to Coding Assistant preset. You can customize your persona later by editing SOUL.md."

Success Criteria

Setup is complete when:

• ~/workspace directory exists with correct structure
• SOUL.md, USER.md, and MEMORY.md are present and personalized
• Preset-specific example files are copied
• User receives confirmation summary
• No errors during directory creation or file operations

Notes

• This skill creates a NEW workspace. For modifying existing workspaces, users should edit files directly or use persona-update skill (if available)
• Template substitution uses simple sed replacement. For complex personalization, consider using the Write tool with template rendering
• The preset examples should include starter files appropriate for each persona type (e.g., coding-assistant includes sample project structure, executive-assistant includes meeting template, etc.)
• All Bash operations should be executed via the Bash tool, never suggested as commands for the user to run manually