crimson_leaf/skills/guides/PAETemplateGuide.md

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

# 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

- 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

- 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

- type: document
  filename: report-name      # saved as {filename}-{task-id}.md

spawn — Create child task

- 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

- type: reply
  style: "Formal and direct."
  target: strategy

close — Mark task complete (always last)

- 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

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)

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)

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

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