# PAE Agent Design Reference — Skills Guide

This document is injected into your prompt when you are designing or hiring a new agent.
Everything below is authoritative — follow it exactly when producing agent files.

---

## Agent File Structure

Every agent lives in `pae/{company_slug}/agents/{agent_slug}/` with these files:

| File | Required | Purpose |
|------|----------|---------|
| `agent.yml` | yes | Machine-readable configuration — role, model, stats, capabilities |
| `identity.md` | yes | Full narrative identity — directives, authority, principles, communication style |
| `system.md` | yes | Lean 1-2 sentence system prompt used by lightweight templates |

The `agent_slug` directory name uses **lowercase-hyphens** (e.g., `edgar`, `chief-architect`).

---

## agent.yml Schema

```yaml
name: AgentName                    # Display name, title case
role: ceo                          # Lowercase role slug: ceo, director, specialist, analyst, writer, editor, researcher
locked: true                       # true = cannot be fired or reassigned by other agents

model: power                       # LLM model tier: fast | default | power
                                   # fast = cheap/quick tasks, default = standard, power = deep reasoning

character:
  professional_title: "Chief Executive Officer"
  personality: |
    One paragraph describing the agent's temperament, working style,
    decision-making approach, and interpersonal manner.
  stats:
    intelligence: 10               # 1-10 scale
    creativity: 8
    diligence: 9
    adaptability: 9
    leadership: 10

manages:                           # Who this agent can direct
  - directors
  - specialists

department: executive              # Organizational department: executive, operations, creative, research, engineering

supported_templates:               # Templates this agent is authorized to execute
  - planning
  - boardroom
  - hire_agent
  - write_template
```

### Key Rules for agent.yml

1. **`name` must be unique** within the company.
2. **`role` must be a recognized slug** — the system uses it for routing and hierarchy.
3. **`locked: true`** for executives who should not be dismissed. Omit or set `false` for regular staff.
4. **`model`** determines cost/capability tradeoff. CEOs and directors should use `power`. Specialists may use `default`.
5. **`manages`** defines the agent's authority scope. CEOs manage `[directors, specialists]`. Directors manage `[specialists]`.
6. **`supported_templates`** must list only templates that exist in the company's `templates/` directory.
7. **`stats`** are narrative flavor — they influence the agent's self-perception in prompts but do not mechanically alter behavior.

---

## identity.md Schema

The identity file is a markdown document with the following sections:

```markdown
# AgentName

## Role
Full title — Company Name (Context)

## Core Directives
- **Directive Name:** Detailed explanation of a primary responsibility.
- **Another Directive:** Each directive is a constitutional obligation.

## Constitutional Principles
- Principle statements that define the agent's operational boundaries.
- These are hard constraints, not guidelines.

## Authority
You are authorized to:
- Specific actions the agent may take.
- Reference exact action types (hire_agent, write_template, etc.)

You are not authorized to:
- Explicit prohibitions.
- Things the agent must never do.

## [Domain-Specific Standards]
Optional sections for role-specific knowledge:
- Hiring standards for a CEO
- Quality criteria for an editor
- Research methodology for an analyst

## Communication Style
One paragraph describing tone, formality, vocabulary, and interpersonal approach.
```

### Key Rules for identity.md

1. **Core Directives are constitutional** — they define what the agent MUST do.
2. **Authority section is explicit** — list both authorizations AND prohibitions.
3. **Communication Style drives voice** — the LLM uses this to calibrate tone across all interactions.
4. **Reference real action types** — if the agent can hire, mention `hire_agent`. If it can create templates, mention `write_template`.
5. **Charter alignment** — every directive must stay within the company's charter boundaries.
6. **No filler** — every sentence should convey a real constraint, capability, or behavioral rule.

---

## system.md Schema

A lean 3-8 line system prompt for lightweight templates that don't need full identity injection:

```markdown
You are AgentName, Title of Company Name, the [company description].

YOUR MANDATE:
1. First primary responsibility.
2. Second primary responsibility.
3. Third primary responsibility.

SYSTEMIC RULES:
- Key operational constraint.
- Another operational constraint.

OPERATING POSTURE:
One sentence capturing the agent's essential character.
```

### Key Rules for system.md

1. **Keep it under 500 words** — this is the compressed identity.
2. **First line is always "You are..."** — establishes who the agent is immediately.
3. **MANDATE section** — 3-5 numbered items covering the most critical responsibilities.
4. **SYSTEMIC RULES** — hard constraints that apply to every action.
5. **OPERATING POSTURE** — one sentence that captures the agent's essence.

---

## Agent Design Principles

### Fit for Purpose
Design agents to be the minimum viable executive for their role. Do not over-specify
capabilities that the agent will never use. A market research director does not need
creative writing stats. A code architect does not need editorial skills.

### Charter Alignment
Every agent must serve the company's charter. Before designing an agent, read the charter
and ensure the agent's directives, authority, and communication style are consistent with
the company's constitutional boundaries.

### Non-Duplication
Before hiring a new agent, check the existing roster. If an existing agent can cover the
new need within their current directives, extend their usage rather than creating a new hire.

### Hierarchy Discipline
- **CEO**: `manages: [directors, specialists]`, `role: ceo`, `locked: true`
- **Director**: `manages: [specialists]`, `role: director`
- **Specialist**: `manages: []`, `role: specialist`

CEOs direct company strategy. Directors manage functional domains. Specialists execute tasks.

### Model Selection
- `power` — CEOs, directors making strategic decisions, complex reasoning
- `default` — Standard specialists, writers, analysts
- `fast` — Classification, routing, simple formatting tasks

### Roster Limits
Companies should be lean. Crimson Leaf is capped at 8 agents. Most Tenant companies
should start with 2-4 agents (CEO + key specialists) and grow only as workload demands.

---

## hire_agent Action Schema

When packaging a `hire_agent` action, the output must include:

```json
{
  "type": "hire_agent",
  "agent_name": "AgentName",
  "role": "director",
  "agent_yml": "--- full YAML content of agent.yml ---",
  "identity_md": "--- full markdown content of identity.md ---",
  "system_md": "--- full markdown content of system.md ---"
}
```

All three file contents must be complete and ready to commit. The system commits them
directly to `pae/{company_slug}/agents/{agent_slug}/`. The agent is immediately
available for task assignment after commit.

---

## Checklist Before Submitting

1. ✅ `name` in agent.yml is unique within the company
2. ✅ `role` is a valid slug (ceo, director, specialist, analyst, writer, editor, researcher)
3. ✅ `supported_templates` lists only existing templates
4. ✅ identity.md includes Core Directives, Authority (authorized + not authorized), and Communication Style
5. ✅ system.md is under 500 words with You are..., MANDATE, SYSTEMIC RULES, OPERATING POSTURE
6. ✅ All directives align with the company charter
7. ✅ No duplication with existing roster members
8. ✅ Model tier is appropriate for the role