Sprint 53a: Skills Loop + Executive Templates

- skills/skills.md: Root catalog/index of all skill guides - skills/guides/PAETemplateGuide.md: How to write PAE-Lang YAML (distilled) - skills/guides/PAEAgentGuide.md: agent.yml + identity.md schemas - skills/guides/CorporateCharterGuide.md: Charter design reference - templates/hire_agent.yml: CEO-authored agent provisioning with PAEAgentGuide injection - templates/write_template.yml: CEO-authored template design with PAETemplateGuide injection - templates/planning.yml: CL-specific boardroom→serialize→dispatch planning - templates/boardroom.yml: CL-specific executive deliberation to consensus Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-03-10 09:06:20 -04:00
parent cdf596c67a
commit 6cf7440726
8 changed files with 1063 additions and 0 deletions
--- a/skills/guides/PAETemplateGuide.md
+++ b/skills/guides/PAETemplateGuide.md
@@ -0,0 +1,331 @@
+# 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