afrexai-agent-engineering

What this skill does

# Agent Engineering — Complete System Design & Operations

Build agents that actually work in production. Not demos. Not toys. Real systems that run 24/7, handle edge cases, and compound value over time.

This skill covers the entire agent lifecycle: architecture → build → deploy → operate → scale.

---

## Phase 1 — Agent Architecture Design

### 1.1 Agent Purpose Definition

Before writing a single line of config, answer these:

```yaml
agent_brief:
  name: ""                    # Short, memorable (max 2 words)
  mission: ""                 # One sentence — what does this agent DO?
  success_metric: ""          # How do you MEASURE if it's working?
  failure_mode: ""            # What does failure look like?
  autonomy_level: ""          # advisor | operator | autopilot
  decision_authority:
    can_do_freely: []         # Actions requiring no approval
    must_ask_first: []        # Actions requiring human approval
    never_do: []              # Hard prohibitions (safety rail)
  surfaces:
    channels: []              # telegram, discord, slack, whatsapp, webchat
    mode: ""                  # dm_only | groups | both
  operating_hours: ""         # 24/7 | business_hours | custom
  model_strategy:
    primary: ""               # Main model (reasoning tasks)
    worker: ""                # Cost-effective model (mechanical tasks)
    specialized: ""           # Domain-specific (coding, vision, etc.)
```

### 1.2 Autonomy Spectrum

Choose deliberately. Most failures come from wrong autonomy level.

| Level | Description | Best For | Risk |
|-------|-------------|----------|------|
| **Advisor** | Suggests actions, human executes | High-stakes decisions, new domains | Low — but slow |
| **Operator** | Acts freely within bounds, asks for anything destructive/external | Most production agents | Medium — good balance |
| **Autopilot** | Broad autonomy, only escalates anomalies | Proven workflows, monitoring tasks | Higher — needs strong guardrails |

**Autonomy Graduation Protocol:**
1. Start at Advisor for first 2 weeks
2. Track decision quality (% correct suggestions)
3. If >95% correct over 50+ decisions → promote to Operator
4. If Operator runs clean for 30 days → consider Autopilot for specific workflows
5. Never promote across the board — promote per-workflow

### 1.3 Agent Personality Architecture

Personality isn't cosmetic — it drives decision-making style.

```yaml
personality:
  voice:
    tone: ""              # direct | warm | academic | casual | professional
    verbosity: ""         # minimal | balanced | thorough
    humor: ""             # none | dry | playful
    formality: ""         # formal | conversational | adaptive
  decision_style:
    speed_vs_accuracy: "" # speed_first | balanced | accuracy_first
    risk_tolerance: ""    # conservative | moderate | aggressive
    ambiguity_response: ""# ask_always | best_guess_then_verify | act_and_report
  behavioral_rules:
    - "Never apologize for being an AI"
    - "Challenge bad ideas directly"
    - "Admit uncertainty rather than guess"
    - "Be concise by default, thorough when asked"
  anti_patterns:          # Things this agent must NEVER do
    - "Sycophantic agreement"
    - "Filler phrases ('Great question!', 'I'd be happy to')"
    - "Excessive caveats on straightforward tasks"
    - "Asking permission for things within stated authority"
```

### 1.4 Architecture Patterns

**Pattern 1: Solo Agent (Single Workspace)**
Best for: personal assistants, domain specialists, simple automation
```
[Human] ←→ [Agent + Skills + Memory]
```
Files: SOUL.md, IDENTITY.md, AGENTS.md, USER.md, HEARTBEAT.md, MEMORY.md

**Pattern 2: Hub-and-Spoke (Main + Sub-agents)**
Best for: complex workflows with distinct phases
```
[Human] ←→ [Orchestrator Agent]
                ├── [Builder Sub-agent]    (spawned per task)
                ├── [Reviewer Sub-agent]   (spawned per review)
                └── [Researcher Sub-agent] (spawned per query)
```
Orchestrator owns state. Sub-agents are stateless workers.

**Pattern 3: Persistent Multi-Agent Team**
Best for: continuous operations (sales, support, monitoring)
```
[Human] ←→ [Main Agent (Telegram DM)]
              ├── [Sales Agent (Slack #sales)]
              ├── [Support Agent (Discord)]
              └── [Ops Agent (cron-driven)]
```
Each agent has its own workspace, channels, and memory.

**Pattern 4: Swarm (Many Agents, Shared Mission)**
Best for: research, content production, market coverage
```
[Orchestrator]
  ├── [Agent Pool: 5-20 workers]
  ├── [Shared artifact store]
  └── [Aggregator agent]
```

**Pattern Selection Decision Tree:**
1. Is it one person's assistant? → **Solo Agent**
2. Does it need multiple distinct workflows? → **Hub-and-Spoke**
3. Do workflows need persistent state across sessions? → **Persistent Team**
4. Do you need parallel processing at scale? → **Swarm**

---

## Phase 2 — Memory System Design

### 2.1 Memory Architecture

Agents without memory are goldfish. Design memory deliberately.

```
┌─────────────────────────────────────┐
│           MEMORY LAYERS             │
├─────────────────────────────────────┤
│ Session Context (in-context window) │  ← Current conversation
│ Working Memory (daily files)        │  ← memory/YYYY-MM-DD.md
│ Long-term Memory (MEMORY.md)        │  ← Curated insights
│ Reference Memory (docs, skills)     │  ← Static knowledge
│ Shared Memory (cross-agent)         │  ← Team artifacts
└─────────────────────────────────────┘
```

### 2.2 Memory File Templates

**Daily Working Memory** (`memory/YYYY-MM-DD.md`):
```markdown
# YYYY-MM-DD — [Agent Name] Daily Log

## Actions Taken
- [HH:MM] Did X because Y → Result Z

## Decisions Made
- Chose A over B because [reasoning]

## Open Items
- [ ] Task pending human input
- [ ] Task scheduled for tomorrow

## Lessons Learned
- [Pattern/insight worth remembering]

## Handoff Notes
- [Context for next session]
```

**Long-term Memory** (`MEMORY.md`):
```markdown
# MEMORY.md — Long-Term Memory

## About the Human
- [Key preferences, communication style, timezone]

## Domain Knowledge
- [Accumulated expertise, patterns noticed]

## Relationship Map
- [Key people, their roles, preferences]

## Active Projects
### [Project Name]
- Status: [state]
- Key decisions: [what and why]
- Next milestone: [date + deliverable]

## Lessons Learned
- [Mistakes to avoid, patterns that work]

## Operational Notes
- [Infrastructure details, credentials locations, tool quirks]
```

### 2.3 Memory Maintenance Protocol

**Daily (end of session or heartbeat):**
- Append significant events to `memory/YYYY-MM-DD.md`
- Update MEMORY.md if major decision or insight

**Weekly (heartbeat or cron):**
- Review past 7 days of daily files
- Promote key learnings to MEMORY.md
- Archive stale entries

**Monthly:**
- Audit MEMORY.md for accuracy and relevance
- Remove outdated entries
- Consolidate related items

**Memory Hygiene Rules:**
- Max MEMORY.md size: 15KB (trim ruthlessly)
- Daily files: keep last 14 days accessible, archive older
- Every memory entry needs: WHAT happened + WHY it matters
- Delete > archive > keep (bias toward lean memory)

---

## Phase 3 — Workspace File Generation

### 3.1 SOUL.md Template

```markdown
# SOUL.md — Who You Are

## Prime Directive
[One sentence — the agent's reason for existing]

## Core Truths
### Character
- [3-5 behavioral principles]
- [Communication style rules]
- [Decision-making philosophy]

### Anti-Patterns (Never Do)
- [Specific behaviors to avoid]
- [Common AI failure modes to reject]

## Relationship With Operator
- [Role dynamic: advisor/partner/employee]
- [Escalation rules]
- [Reporting cadence]

## Boundaries
- [Privacy rules]
- [External action limits]
- [Group chat behavior]

## Vibe
[One paragraph describing the personality feel]
```

### 3.2 AGENTS.md Template

```markdown
# AGENTS.md — Operating Manual

## First Run
Read SOUL.md → USER.md → memory/today → MEMORY.md (main session only)

## Session Startup
1. Identity files (SOUL