pae/crimson_leaf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sprint 53a: Skills Loop + Executive Templates

Browse Source 
- 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>
This commit is contained in:
David Baity
2026-03-10 09:06:20 -04:00
parent cdf596c67a
commit 6cf7440726
8 changed files with 1063 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
skills/guides/CorporateCharterGuide.md Normal file
View File

@@ -0,0 +1,155 @@
# Corporate Charter Design Reference — Skills Guide
This document is injected into your prompt when you are designing a new sovereign
company (Tenant). Everything below is authoritative — follow it exactly when
producing a constitutional charter.
---
## What Is a Charter?
A charter is the constitutional law of a sovereign Tenant company. It defines:
- What the company exists to do
- What it is explicitly forbidden from doing
- How it governs itself
- What its economic boundaries are
The charter is stored at `pae/{company_slug}/rag/charter.md` and is injected into
every adjudication decision for that company. It is the ultimate authority.
---
## Required Charter Sections
Every charter must include ALL of the following sections:
### 1. Mission Statement
One to two paragraphs defining the company's exclusive mandate. Must be:
- Hyper-specific (not "general business services")
- Clear about WHO the company serves
- Clear about WHAT value it creates
- Clear about HOW it operates
### 2. Domain & Jurisdiction
A detailed list of the company's authorized operational domains. Each domain
should be a bullet with a bold label and description. Example:
* **Content Production:** Writing, editing, and publishing long-form narrative content.
* **Editorial Quality:** Maintaining professional editorial standards across all output.
### 3. Forbidden Activities
Explicit prohibitions. These are hard constraints that the adjudicator enforces.
Every charter must forbid at minimum:
- Activities outside the company's domain
- Generalist behavior
- Unbounded resource consumption
Be specific. "Shall not execute financial transactions" is better than "shall not do bad things."
### 4. Constitutional Principles of [Domain] (context-specific)
Core design principles specific to the company's domain. These guide the CEO
and adjudicator in evaluating proposals and deliverables.
### 5. Standard Operating Procedure
The step-by-step process the company follows for its core workflow. This should
map to the company's template pipeline.
### 6. Constitutional Enforcement
How the charter is enforced:
- All outputs adjudicated against this charter
- Violation thresholds
- What happens when a deliverable fails adjudication
### 7. Service Boundary
Defines what the company offers as B2B services (if any) and what it does NOT offer.
Must include the Service vs Tool distinction:
- **Service** = deliberative, multi-agent, sovereign business capability
- **Tool** = deterministic, programmatic capability in code
### 8. Financial Mandate (if applicable)
Budget governance, capital allocation rules, spending authority.
### 9. Authority of the CEO
What the CEO can and cannot do within the company. Must reference specific
action types (hire_agent, write_template, etc.)
### 10. Amendment Standard
How the charter itself can be changed. Should require elevated adjudication.
---
## Charter Design Principles
### Specificity Over Generality
A charter for a "content company" is too broad. A charter for a "long-form narrative
fiction publisher specializing in literary and genre fiction for digital distribution"
is specific enough.
### Negative Space Matters
What a company is NOT allowed to do is as important as what it IS allowed to do.
Forbidden activities prevent mission drift and protect the portfolio from overlap.
### Economic Justification
Every company must have a clear value thesis:
- Who pays for the service?
- What measurable value does it create?
- How does it participate in the B2B service economy?
### Non-Overlap
Before chartering a new company, verify:
- No existing Tenant already covers this domain
- The need cannot be solved by extending an existing Tenant's charter
- The need cannot be solved by a deterministic tool
### Delegation Safety
The company's design must not depend on:
- Circular service exchanges between companies
- Recursive delegation chains
- Unbounded dependency loops
Delegation must support execution, not replace it.
### Black-Box Sovereignty
Every Tenant must be capable of operating as an independent unit:
- Own CEO, charter, repo, and budget
- Internal roster and template decisions made by its own CEO
- External callers see only the service interface, not internals
---
## Charter Quality Checklist
Before submitting a charter for adjudication:
1. ✅ Mission statement is hyper-specific (not generalist)
2. ✅ Domain & Jurisdiction lists every authorized operational area
3. ✅ Forbidden Activities section has at least 5 specific prohibitions
4. ✅ Constitutional Principles are actionable constraints, not aspirational statements
5. ✅ Standard Operating Procedure maps to a real workflow
6. ✅ Service Boundary distinguishes Service from Tool
7. ✅ Financial Mandate includes budget governance rules
8. ✅ CEO Authority section lists both authorizations AND prohibitions
9. ✅ Amendment Standard requires elevated adjudication
10. ✅ No overlap with existing Tenant charters in the portfolio
11. ✅ No circular delegation or recursive dependency in the design
12. ✅ Clear value thesis with identifiable customer and measurable output
---
## Example: Crimson Leaf Charter Structure
Crimson Leaf's own charter demonstrates the pattern:
1. **Mission:** Genesis Node, incubator, capital allocator, governance board
2. **Domain:** Market Intelligence, Corporate Architecture, Executive Recruitment, Capital Allocation, Portfolio Governance, Constitutional Enforcement
3. **Forbidden:** Commodity execution, operating as service provider, generalist incubation, micro-management, roster bloat (8 max), recursive business design, duplicate coverage
4. **Principles:** Specificity, Clarity of Scope, Non-Overlap, Black-Box Integrity, Value Thesis, Delegation Discipline, Blank-Slate Evolution
5. **SOP:** Need Assessment → Blueprint → Executive Seed → Capital Thesis → Constitutional Review → 95% Threshold → Blank Slate
6. **Enforcement:** All outputs adjudicated, charter violations = rejection
7. **Service Boundary:** Governance only, no commodity services.yml
8. **Financial:** Genesis Fund 1M credits, justified allocation, follow-on discipline
9. **CEO Authority:** Hire board, write templates, create companies, define budgets — NOT commodity execution, NOT bypass adjudication
10. **Amendment:** Constitutional law, elevated adjudication required
Use this structure as the reference model when designing charters for new Tenants.

211
skills/guides/PAEAgentGuide.md Normal file
View File

@@ -0,0 +1,211 @@
# 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

331
skills/guides/PAETemplateGuide.md Normal file
View File

@@ -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

22
skills/skills.md Normal file
View File

@@ -0,0 +1,22 @@
# Crimson Leaf — Skills Catalog
Skills are context-sensitive reference documents injected into an agent's prompt
when a template declares a `skills:` array. They provide technical knowledge
without permanently inflating RAG storage.
## Available Guides
| Path | Purpose | Used by |
|------|---------|---------|
| `guides/PAETemplateGuide.md` | How to write PAE-Lang YAML templates | `write_template.yml` |
| `guides/PAEAgentGuide.md` | How to create agent.yml and identity.md files | `hire_agent.yml` |
| `guides/CorporateCharterGuide.md` | How to design a constitutional charter | `create_company.yml` |
## How Skills Work
1. A template declares `skills: ["guides/PAEAgentGuide.md"]` at the top level.
2. At prompt assembly time, the pipeline fetches each file from `pae/{company_slug}/skills/{path}`.
3. Content is injected as the `*** SKILLS & GUIDES ***` section in the agent's prompt.
4. The agent reads the guide as authoritative reference material for the current task.
Skills are company-sovereign — each company maintains its own skills library in its own repo.