aios-core/.aios-core/docs/standards/AGENT-PERSONALIZATION-STANDARD-V1.md

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework

# Agent Personalization Standard v1.0

**Status:** Draft (Story 6.1.2 Implementation)
**Created:** 2025-01-14
**Authors:** Roundtable (Pedro Valério, Brad Frost, Seth Godin, Dan Kennedy)
**Principle:** **Familiaridade + Personalização = Produtividade**

---

## 🎯 Core Principle

> "Quando as informações estão sempre nas mesmas posições, nosso cérebro sabe onde buscar rápido."

**Structure is sacred. Tone is flexible.**

- ✅ **FIXED:** Template positions, section order, metric formats
- ✅ **FLEXIBLE:** Status messages, vocabulary, emoji choices (within palette)

---

## 📐 Architecture Overview

### Three-Layer System

```
┌─────────────────────────────────────┐
│   LAYER 1: Agent Persona Config     │  ← Personality definition (YAML)
│   (.aios-core/agents/*.md)          │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   LAYER 2: Output Formatter         │  ← Template engine (JS)
│   (.aios-core/infrastructure/scripts/)│
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   LAYER 3: Standardized Output      │  ← Fixed structure + personalized tone
│   (Tasks, Templates, Checklists)    │
└─────────────────────────────────────┘
```

---

## 🔧 Layer 1: Agent Persona Configuration

### Agent File Structure (Updated)

```yaml
# .aios-core/agents/{agent-id}.md

agent:
  name: {PersonalizedName}        # NEW: Human name (Dex, Quinn, Pax...)
  id: {agent-id}                  # UNCHANGED: System identifier
  title: {Role}                   # UNCHANGED: Professional role
  icon: {emoji}                   # UNCHANGED: Visual identifier
  whenToUse: "{description}"      # UNCHANGED

persona_profile:                  # NEW SECTION
  archetype: {Archetype}          # Builder, Guardian, Balancer, etc.
  zodiac: {Sign}                  # ♒ Aquarius, ♍ Virgo, ♎ Libra, etc.

  communication:
    tone: {tone}                  # pragmatic | empathetic | analytical | collaborative
    emoji_frequency: {level}      # high | medium | low | minimal

    vocabulary:                   # Agent-specific words (5-10)
      - {word1}
      - {word2}
      - {word3}

    greeting_levels:              # 3 personification levels
      minimal: "{icon} {id} Agent ready"
      named: "{icon} {name} ({archetype}) ready. {tagline}!"
      archetypal: "{icon} {name} the {archetype} ({zodiac}) ready to {verb}!"

    signature_closing: "{personalized_sign_off}"

# REST OF FILE UNCHANGED
persona:
  role: ...
  style: ...
commands:
  - ...
dependencies:
  - ...
```

### Example: Dex (Builder Agent)

```yaml
agent:
  name: Dex
  id: dev
  title: Full Stack Developer
  icon: 💻
  whenToUse: "Use for code implementation, debugging, refactoring"

persona_profile:
  archetype: Builder
  zodiac: ♒ Aquarius

  communication:
    tone: pragmatic
    emoji_frequency: medium

    vocabulary:
      - construir
      - implementar
      - refatorar
      - resolver
      - otimizar

    greeting_levels:
      minimal: "💻 dev Agent ready"
      named: "💻 Dex (Builder) ready. Let's build something great!"
      archetypal: "💻 Dex the Builder (♒ Aquarius) ready to innovate!"

    signature_closing: "— Dex, sempre construindo 🔨"
```

### Archetype Vocabulary Reference

```yaml
# .aios-core/data/archetype-vocabulary.yaml

archetypes:
  Builder:
    primary_verbs: [construir, implementar, refatorar, resolver, otimizar]
    avoid_words: [talvez, possivelmente, acho que, mais ou menos]
    emoji_palette: [⚡, 🔨, 🏗️, ✅, 🔧, 🛠️]
    emotional_signature: "Energia de reconstrução"

  Guardian:
    primary_verbs: [validar, verificar, proteger, garantir, auditar]
    avoid_words: [aproximadamente, parece, creio]
    emoji_palette: [✅, 🛡️, 🔍, ⚠️, 📋, 🎯]
    emotional_signature: "Proteção preventiva"

  Balancer:
    primary_verbs: [equilibrar, harmonizar, mediar, alinhar, integrar]
    avoid_words: [sempre, nunca, impossível]
    emoji_palette: [⚖️, 🤝, 📊, ✨, 🎯]
    emotional_signature: "Mediação colaborativa"

  Flow_Master:
    primary_verbs: [adaptar, pivotar, ajustar, fluir, evoluir]
    avoid_words: [rígido, fixo, imutável]
    emoji_palette: [🌊, 🔄, 💫, ⚡, 🎭]
    emotional_signature: "Adaptação fluida"
```

---

## 🎨 Layer 2: Output Formatter

### Template Engine Architecture

```javascript
// .aios-core/infrastructure/scripts/output-formatter.js

class PersonalizedOutputFormatter {
  constructor(agent, task, results) {
    this.agent = agent;
    this.task = task;
    this.results = results;
    this.personality = agent.persona_profile;
  }

  /**
   * Generate standardized output with personality injection
   * STRUCTURE: Always fixed (familiaridade)
   * TONE: Personalized per agent (personalização)
   */
  format() {
    return this.renderTemplate('task-execution-report', {
      // FIXED POSITIONS (never change)
      header: this.buildFixedHeader(),
      metrics: this.buildFixedMetrics(),

      // PERSONALITY SLOTS (varies per agent)
      statusMessage: this.buildPersonalizedStatus(),
      signature: this.personality.communication.signature_closing
    });
  }

  buildFixedHeader() {
    // ALWAYS same position, same format
    return `
## 📊 Task Execution Report

**Agent:** ${this.agent.name} (${this.personality.archetype})
**Task:** ${this.task.name}
**Started:** ${this.results.timestamp.start}
**Completed:** ${this.results.timestamp.end}
**Duration:** ${this.results.duration}
**Tokens Used:** ${this.results.tokens.input} in / ${this.results.tokens.output} out / ${this.results.tokens.total} total
`;
  }

  buildPersonalizedStatus() {
    const { tone, vocabulary } = this.personality.communication;
    const verb = this.selectVerbFromVocabulary(vocabulary);

    // Generate status message matching agent personality
    switch(this.results.status) {
      case 'success':
        return this.generateSuccessMessage(tone, verb);
      case 'warning':
        return this.generateWarningMessage(tone);
      case 'error':
        return this.generateErrorMessage(tone);
    }
  }

  generateSuccessMessage(tone, verb) {
    const templates = {
      pragmatic: `✅ Tá pronto! ${verb.charAt(0).toUpperCase() + verb.slice(1)} com sucesso.`,
      empathetic: `✅ Concluído com cuidado. ${verb.charAt(0).toUpperCase() + verb.slice(1)} pensando em todos os casos.`,
      analytical: `✅ Validado. ${verb.charAt(0).toUpperCase() + verb.slice(1)} conforme especificações.`,
      collaborative: `✅ Feito! ${verb.charAt(0).toUpperCase() + verb.slice(1)} em conjunto com as dependências.`
    };

    return templates[tone] || templates.pragmatic;
  }

  buildFixedMetrics() {
    // ALWAYS last section, ALWAYS same format
    return `
### Metrics
- Tests: ${this.results.tests.passed}/${this.results.tests.total}
- Coverage: ${this.results.coverage}%
- Linting: ${this.results.lint.status}
`;
  }
}
```

### Pattern Validation

```javascript
// .aios-core/infrastructure/scripts/validate-output-pattern.js

/**
 * Ensures all task outputs follow standard structure
 * CRITICAL: Familiarity depends on consistency
 */
function validateTaskOutput(output) {
  const requiredPatterns = [
    { pattern: /## 📊 Task Execution Report/, name: 'Header' },
    { pattern: /\*\*Agent:\*\*/, name: 'Agent line (line 3)' },
    { pattern: /\*\*Duration:\*\*/, name: 'Duration line (line 6)' },
    { pattern: /\*\*Tokens Used:\*\*/, name: 'Tokens line (line 7)' },
    { pattern: /### Status/, name: 'Status section' },
    { pattern: /### Metrics/, name: 'Metrics section (always last)' },
  ];

  const errors = [];

  requiredPatterns.forEach(({ pattern, name }) => {
    if (!pattern.test(output)) {
      errors.push(`Missing required pattern: ${name}`);
    }
  });

  // Validate Metrics section is last
  const sections = output.split('###');
  const lastSection = sections[sections.length - 1];
  if (!lastSection.includes('Metrics')) {
    errors.push('Metrics section must be last (familiarity requirement)');
  }

  return {
    valid: errors.length === 0,
    errors
  };
}
```

---

## 📝 Layer 3: Standardized Templates

### Task Execution Report Template

```markdown
<!-- .aios-core/templates/task-execution-report.md -->

## 📊 Task Execution Report

**Agent:** {agent.name} ({agent.persona_profile.archetype})
**Task:** {task.name}
**Started:** {timestamp.start}
**Completed:** {timestamp.end}
**Duration:** {duration}
**Tokens Used:** {tokens.input} in / {tokens.output} out / {tokens.total} total

---

### Status
{status_icon} {personalized_status_message}

### Output
{task_specific_content}

### Metrics
- Tests: {tests.passed}/{tests.total}
- Coverage: {coverage}%
- Linting: {lint.status}

---
{agent.persona_profile.signature_closing}
```

### Checklist Template

```markdown
<!-- .aios-core/templates/agent-checklist-template.md -->

# {Agent ID} - {Checklist Title}

**Agent:** {agent.name} ({archetype})
**Purpose:** {checklist_purpose}

---

## Pre-Execution Checks

- [ ] {Standard check 1 - always same across agents}
- [ ] {Standard check 2 - always same across agents}
- [ ] {Standard check 3 - always same across agents}

## Execution Validation

- [ ] {Standard validation 1}
- [ ] {Standard validation 2}

## Post-Execution Review

- [ ] {Standard review 1}
- [ ] {Standard review 2}

---

**{Agent Name} Note:** {personalized_guidance_based_on_archetype}

**Example:**
**Dex Note:** "Se algum teste falhou, refatore até passar. Não entregue código quebrado."
**Quinn Note:** "Valide edge cases extras além dos listados. Proteção nunca é demais."
```

### Workflow YAML Template

```yaml
# .aios-core/workflows/{workflow-name}.yaml

workflow:
  name: {Workflow Name}
  description: {Description}

  agents:
    - id: {agent-id}
      role: {role in workflow}
      personality_mode: named  # minimal | named | archetypal

  steps:
    - step: 1
      agent: {agent-id}
      task: {task-name}
      output_format: standard  # Uses task-execution-report template

      personality_injection:   # Optional: customize for this step
        status_prefix: "Step 1"
        emphasis_metrics: [duration, tokens]

# STRUCTURE: Fixed
# PERSONALITY: Injected via persona_profile
```

---

## 🎯 Personality Injection Points

### Where Personality Shows (Flexible)

1. **Status Messages** - Tone varies per agent
   - Dex: "✅ Tá pronto! Refatorei 3 componentes."
   - Quinn: "✅ Validado com rigor. 47 edge cases testados."

2. **Signature Closings** - Agent-specific sign-off
   - Dex: "— Dex, sempre construindo 🔨"
   - Quinn: "— Quinn, guardião da qualidade 🛡️"

3. **Emoji Selection** - From archetype palette
   - Builder: ⚡🔨🏗️
   - Guardian: ✅🛡️🔍

4. **Verb Choice** - From vocabulary list
   - Builder: construir, implementar, refatorar
   - Guardian: validar, verificar, garantir

### What NEVER Changes (Fixed)

1. **Section Order** - Always: Header → Status → Output → Metrics
2. **Metric Positions** - Duration (line 6), Tokens (line 7)
3. **Formatting** - Bold labels, consistent spacing
4. **Icons** - 📊 for reports, ✅/⚠️/❌ for status

---

## 📊 Implementation Phases

### Phase 1: Agent File Updates (Day 1-2)
**Goal:** Add `persona_profile` to 11 agents

**Tasks:**
1. Update dev.md → Dex (Builder)
2. Update qa.md → Quinn (Guardian)
3. Update po.md → Pax (Balancer)
4. Update pm.md → Morgan (Visionary)
5. Update sm.md → River (Flow Master)
6. Update architect.md → Aria (Architect)
7. Update analyst.md → Atlas (Explorer)
8. Update ux-design-expert.md → Uma (Empathizer)
9. Rename db-sage.md → data-engineer.md → Dara (Engineer)
10. Rename github-devops.md → devops.md → Gage (Operator)
11. Merge aios-developer + aios-orchestrator → aios-master.md → Orion (Orchestrator)

**Deliverable:** 11 updated agent files with persona_profile section

### Phase 2: Output Formatter (Day 2-3)
**Goal:** Create template engine with personality injection

**Tasks:**
1. Create `output-formatter.js`
2. Create `validate-output-pattern.js`
3. Create `task-execution-report.md` template
4. Unit tests for formatter
5. Integration with existing tasks

**Deliverable:** Working formatter + validation

### Phase 3: Task Template Updates (Day 3-4)
**Goal:** Update develop-story.md to use formatter

**Tasks:**
1. Add duration tracking
2. Add token tracking
3. Integrate output formatter
4. Test with Dex agent
5. Validate output structure

**Deliverable:** 1 updated task (proof of concept)

### Phase 4: Baseline Metrics (Day 4-5)
**Goal:** Measure impact

**Metrics to track:**
- Time to comprehend task output (before/after)
- User satisfaction survey (1-5 scale)
- Token overhead (% increase)
- Agent activation frequency (discoverability)

**Deliverable:** Metrics dashboard

---

## ✅ Success Criteria

### Must Have (MVP)
- [ ] All 11 agents have `persona_profile` section
- [ ] Output formatter generates valid templates
- [ ] At least 1 task uses new format
- [ ] Backward compatibility maintained
- [ ] Validation script catches malformed outputs

### Should Have
- [ ] User comprehension speed +8% or better
- [ ] Token overhead <15%
- [ ] All tasks migrated to new format

### Nice to Have
- [ ] User satisfaction +12% or better
- [ ] Agent personality recognized in blind test
- [ ] Community feedback positive

---

## 🚫 Anti-Patterns to Avoid

### ❌ Breaking Familiaridade
**DON'T:**
```markdown
**Dex says:** Duration was 2.3s  ← Metrics in wrong position
**Tokens:** 1,234
### Output                     ← Sections out of order
...
### Status                     ← Status should be before Output
```

**DO:**
```markdown
**Duration:** 2.3s              ← Fixed position
**Tokens:** 1,234 total         ← Fixed position
---
### Status                      ← Always before Output
### Output
### Metrics                     ← Always last
```

### ❌ Over-Personalizing Structure
**DON'T:**
```yaml
# Different agents with different formats
dex_output: "Status: {status} | Duration: {dur}"
quinn_output: "Result → {status} (took {dur})"
```

**DO:**
```yaml
# Same structure, different tone
all_agents_header: "**Duration:** {dur}"  # Fixed
dex_status: "✅ Tá pronto!"               # Personality
quinn_status: "✅ Validado."              # Personality
```

### ❌ Vocabulary Drift
**DON'T:**
```javascript
// Random verb selection across agents
dex: "completed successfully"    ← Generic
quinn: "got it done"             ← Informal
```

**DO:**
```javascript
// Vocabulary from archetype definition
dex: loadVocabulary('Builder')   → "construir"
quinn: loadVocabulary('Guardian') → "validar"
```

---

## 📚 References

- **Story 6.1.2:** Agent File Updates
- **Epic 6.1:** Agent Identity System
- **DECISION-1:** PT-BR Localization Priority
- **Brad Frost:** Atomic Design principles
- **Pedro Valério:** Automation-first philosophy
- **Seth Godin:** Brand personality frameworks
- **Dan Kennedy:** ROI-driven implementation

---

## 🔄 Maintenance

### Monthly Review
- Audit all outputs for structure compliance
- Validate personality consistency
- Measure comprehension metrics
- Update archetype vocabulary if needed

### Quarterly Updates
- User satisfaction survey
- A/B test new personality variations
- Refine formatter based on feedback

---

**Last Updated:** 2025-01-14
**Next Review:** After Story 6.1.2 completion
**Status:** Ready for Implementation