crimson_leaf/skills/guides/PAEAgentGuide.md

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

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:

# 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:

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:

{
  "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