# PAE-Lang Template Reference — Skills Guide

This document is injected into your prompt when you are writing or modifying
PAE YAML templates. Everything below is authoritative — follow it exactly.

---

## What You Write Is What the LLM Receives

There are no hidden defaults. If you omit `system:`, the system message is empty.
If you omit a section key, that context is not injected. Be explicit.

---

## Top-Level Template Keys

| Key | Required | Purpose |
|-----|----------|---------|
| `name` | yes | Must match the filename without `.yml` |
| `description` | no | Human summary, appears in template catalog |
| `debug` | no | `true` = commit full tasklog to tasklogs/ |
| `system` | no | Sets `role:system`. Options: `agent_prompt`, a builder name, or a literal string |
| `model` | no | Template-level model override: `fast`, `default`, `power`, `gemini`, `grok` |
| `requires` | no | List of `context_vars` keys that must be present before step 0 |
| `agent_prompt` | no | Files assembled into agent identity. `[]` = empty identity |
| `participant_prompt` | no | Same as agent_prompt but for boardroom participants |
| `builders` | no | Named inline content blocks with `{variable}` interpolation |
| `sections` | no | Ordered list of section keys for `role:user`. Default: `[project, history, rag, message, instructions]` |
| `skills` | no | List of skill file paths fetched from `pae/{company}/skills/` and injected as `*** SKILLS & GUIDES ***` |
| `steps` | yes | List of execution steps. At least 1 required |
| `adjudication` | no | Quality gate configuration |

### system: Options

- `system: agent_prompt` — assemble from `agent_prompt:` file list
- `system: my_builder` — use a named builder (interpolated)
- `system: "literal text"` — verbatim string
- absent — system message is empty

### agent_prompt: Patterns

```yaml
# Full identity + RAG
agent_prompt:
  - "= identity.md"
  - "agent.rag.json"

# Lean identity (1-2 sentences)
agent_prompt:
  - system.md
```

When using `system.md` (lean), remove `agent` from `sections:` to avoid duplication.

---

## Section Keys

Sections are injected into `role:user` in the order declared. Available keys:

| Key | Prompt Block Title | When to Include |
|-----|-------------------|-----------------|
| `scene` | `*** LOCATION CONTEXT ***` | Boardroom/narrative framing |
| `agent` | `*** CHAIR ***` | Agent needs self-awareness |
| `project` | `*** PROJECT DESCRIPTION ***` | Almost always |
| `history` | `*** CONVERSATION HISTORY ***` | Prior context needed |
| `rag` | `*** CONTEXT FROM RAG DATABASES ***` | Project knowledge needed |
| `roster` | `*** TEAM ROSTER ***` | Planning, intake, assignment |
| `templates` | `*** AVAILABLE TASK TEMPLATES ***` | Planning, classification |
| `participants` | `*** PARTICIPANTS ***` | Multi-agent tasks |
| `participants_prompt` | `*** PARTICIPANT IDENTITIES ***` | Boardroom |
| `sender_identity` | `*** SENDER IDENTITY ***` | Personalizing replies |
| `pending_human_tasks` | `*** YOUR PENDING HUMAN TASKS ***` | Human-action resolution |
| `skills` | `*** SKILLS & GUIDES ***` | Template declares `skills:` array |
| `message` | `*** CURRENT MESSAGE ***` | Always |
| `instructions` | `*** RESPONSE SPECIFICATIONS ***` | Almost always, place last |
| `rejection_feedback` | `*** PREVIOUS ATTEMPT FEEDBACK ***` | Retry/adjudication loops |
| `deliverables` | `*** PROJECT DELIVERABLES ***` | Prior work context |
| *builder name* | `*** BUILDER NAME ***` | Custom inline content |

**Order matters.** Put `message` near end. Put `instructions` last.

---

## Step Types

### think — LLM call
```yaml
- type: think
  hint: "Instruction appended to user message."
  model: power              # step-level override
  agent: assigned            # assigned | "Agent Name" | first_available
  scene: "Narrative frame."
  rotate_participants: false
  loop:
    max_iterations: 3        # boardroom consensus loop
```

Boardroom behavior = `loop: {max_iterations: N}` + `rotate_participants: true`.
Consensus detected when output contains `"consensus_reached: true"`.

### package — Format output as typed JSON
```yaml
- type: package
  packet_type: IntakeResponse
  schema:
    actions:
      - type: create_task
        task_name: "string"
        agent_name: "string"
  hint: "Extra instruction for the Scribe LLM"
  insert_children: true      # read result.tasks and create child tasks
```

### document — Write deliverable to Gitea
```yaml
- type: document
  filename: report-name      # saved as {filename}-{task-id}.md
```

### spawn — Create child task
```yaml
- type: spawn
  task_type: template_name
  task_name: "Child task name"
  agent: AgentName
  wait: false                # true = suspend parent until child completes
```

### reply — Send text reply
```yaml
- type: reply
  style: "Formal and direct."
  target: strategy
```

### close — Mark task complete (always last)
```yaml
- type: close
  rag_update: true           # true = embed output into project RAG
```

---

## Action Types (package step output)

These are emitted by a `package` step and dispatched by the intake dispatcher:

| Action | Purpose | Required Fields |
|--------|---------|-----------------|
| `create_task` | Create new task | `task_name`, `agent_name` or `agents` |
| `hire_agent` | Provision new agent | `agent_name`, `role`, `agent_yml`, `identity_md`, `system_md` |
| `write_template` | Create/update template | `company_slug`, `template_name`, `template_yaml` |
| `create_company` | Incubate new Tenant | `company_slug`, `company_name`, `charter`, `ceo_seed` |
| `delegate` | Assign by capability | `task_name`, `capability` |
| `request_service` | B2B delegation | `provider_company`, `service_name`, `message` |
| `request_tool` | HITL tool request | `tool_name`, `reason` |

---

## Variable Interpolation

Available in `builders:`, `system:`, and step `hint:` fields:

| Variable | Value |
|----------|-------|
| `{agent.name}` | Agent's name |
| `{agent.role}` | Agent's role/title |
| `{agent.identity}` | Full identity block |
| `{project.name}` | Project name |
| `{project.description}` | Project description |
| `{task.id}` | Task UUID |
| `{task.message}` | Task message |
| `{task.iteration}` | Loop iteration (0-based) |
| `{steps[N].text}` | Text output of step N (valid from step N+1 onward) |

Unknown variables are left as-is — no crash.

---

## The Iron Rule

**NEVER mix thinking and formatting in the same LLM step.**

- A `think` step reasons freely — prose, analysis, debate.
- A `package` step serializes ONLY — zero new thinking, just structured output.

If a template needs the LLM to reason AND produce structured JSON, use two steps:
1. `think` — reason about the problem
2. `package` — serialize the decisions into JSON

---

## Template Patterns

### Standard Production Template
```yaml
name: my_task
description: "What this template does."
system: agent_prompt
agent_prompt:
  - "= identity.md"
sections:
  - project
  - history
  - rag
  - message
  - instructions
steps:
  - type: think
    hint: |
      [Detailed instruction for the agent.]
  - type: document
    filename: output-name
  - type: close
    rag_update: true
```

### Planning Template (boardroom → serialize → dispatch)
```yaml
name: my_planning
description: "Deliberation then child task dispatch."
system: agent_prompt
agent_prompt:
  - "= identity.md"
participant_prompt:
  - "= identity.md"
sections:
  - agent
  - project
  - history
  - rag
  - participants
  - participants_prompt
  - roster
  - templates
  - message
  - instructions
steps:
  - type: think
    rotate_participants: true
    loop:
      max_iterations: 3
    hint: |
      Deliberate on the plan. Include "consensus_reached: true" when agreed.
  - type: think
    agent: first_available
    hint: |
      Serialize the agreed plan into task records. Do NOT re-deliberate.
  - type: package
    packet_type: PlanningResponsePacket
    schema:
      tasks:
        - task_name: "string"
          description: "string"
          agents: ["string"]
          task_type: "string"
          priority: "integer 1-5"
    insert_children: true
  - type: close
    rag_update: false
adjudication:
  enabled: false
```

### Boardroom Template (deliberation only)
```yaml
name: boardroom_topic
description: "Multi-agent deliberation to consensus."
system: agent_prompt
participant_prompt:
  - "= identity.md"
sections:
  - agent
  - project
  - participants
  - participants_prompt
  - message
  - instructions
steps:
  - type: think
    rotate_participants: true
    loop:
      max_iterations: 3
    hint: |
      Debate the topic. Include "consensus_reached: true" when genuinely agreed.
  - type: think
    agent: first_available
    hint: |
      Synthesize the boardroom transcript into a clear recommendation.
  - type: close
    rag_update: false
adjudication:
  enabled: false
```

---

## Adjudication Configuration

```yaml
adjudication:
  enabled: true
  pass_threshold: 80       # score below this = retry
  deliverable_type: consumer  # consumer | coordination
  criteria:
    quality:
      weight: 50
      description: "Output meets professional standards"
    adherence:
      weight: 50
      description: "Follows the project brief"
```

- `consumer` — final human-facing content
- `coordination` — internal working documents
- Criteria weights must sum to 100
- Charter compliance is automatically enforced during adjudication

---

## Constraints

1. `name:` must match the filename (`my_template.yml` → `name: my_template`)
2. `steps:` is required — every template needs at least one step
3. `close` must be the last step
4. `system:` is opt-in — absent means empty system message
5. `agent_prompt: []` means empty — not the same as absent
6. `{steps[N].text}` is only valid from step N+1 onward
7. `process_ledger` is AR-only — only valid in `Adjudication.yml`
8. `requires:` validates before step 0 — missing vars fail the task immediately