xingyue
4de13cea44
- moderator-reference: use nested map graph format matching evaluate.ts - yaml-reference: use goal/procedure/output/capabilities/frontmatter fields matching actual WorkflowPayload, not fabricated system/outputSchema - skill.test.ts: replace hardcoded absolute path with __dirname-relative - skill.test.ts: assert 'frontmatter' instead of 'outputSchema'
83 lines
2.9 KiB
TypeScript
83 lines
2.9 KiB
TypeScript
export function generateYamlReference(): string {
|
|
return `# Workflow YAML Schema Reference
|
|
|
|
## Top-Level Structure
|
|
|
|
A workflow YAML file defines the complete workflow specification:
|
|
|
|
\`\`\`yaml
|
|
name: solve-issue # verb-first kebab-case identifier
|
|
description: "..." # human-readable description
|
|
|
|
roles: # named actors in the workflow
|
|
planner:
|
|
description: "Analyzes issue and outputs a plan"
|
|
goal: "You are a planning agent."
|
|
capabilities:
|
|
- issue-analysis
|
|
- planning
|
|
procedure: |
|
|
1. Read the issue
|
|
2. Produce a test spec
|
|
output: "Output the plan summary. Set $status to ready or insufficient_info."
|
|
frontmatter: # JSON Schema for structured output (drives routing)
|
|
oneOf:
|
|
- properties:
|
|
$status: { const: ready }
|
|
plan: { type: string }
|
|
required: [$status, plan]
|
|
- properties:
|
|
$status: { const: insufficient_info }
|
|
required: [$status]
|
|
|
|
graph: # status-based routing (nested map)
|
|
$START:
|
|
_: { role: planner, prompt: "Analyze the issue." }
|
|
planner:
|
|
ready: { role: developer, prompt: "Implement plan {{{plan}}}." }
|
|
insufficient_info: { role: $END, prompt: "Not enough info." }
|
|
\`\`\`
|
|
|
|
## roles
|
|
|
|
Each role defines an actor in the workflow:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| \`description\` | string | Short description of the role's purpose |
|
|
| \`goal\` | string | System-level goal statement for the agent |
|
|
| \`capabilities\` | string[] | Tags describing what the role can do |
|
|
| \`procedure\` | string | Step-by-step instructions for the agent |
|
|
| \`output\` | string | Description of expected output format |
|
|
| \`frontmatter\` | JSON Schema | Defines the structured output the agent must produce |
|
|
|
|
### frontmatter
|
|
|
|
The \`frontmatter\` field is a standard JSON Schema object. The extract pipeline validates agent output against it. Key conventions:
|
|
- \`$status\` field drives routing decisions in the graph
|
|
- Use \`const\` or \`enum\` to constrain status values
|
|
- Use \`oneOf\` to define multiple valid output shapes (one per status)
|
|
- All \`required\` fields must appear in the agent's frontmatter output
|
|
|
|
## graph
|
|
|
|
The graph is a nested map defining status-based routing:
|
|
|
|
\`\`\`
|
|
Record<Role | "$START", Record<Status, { role: string, prompt: string }>>
|
|
\`\`\`
|
|
|
|
| Level | Key | Value |
|
|
|-------|-----|-------|
|
|
| Outer | Role name or \`$START\` | Status map for that role |
|
|
| Inner | \`$status\` value (or \`_\` for unconditional) | Target: \`{ role, prompt }\` |
|
|
|
|
### Special Nodes
|
|
- \`$START\` — entry point; uses status key \`_\` (unconditional, no previous output)
|
|
- \`$END\` — terminal node; thread completes when reached
|
|
|
|
### Edge Prompts
|
|
Prompts use triple-brace Mustache templates (\`{{{field}}}\`) to interpolate values from the previous step's output. Example: \`"Implement plan {{{plan}}} in repo {{{repoPath}}}."\`
|
|
`;
|
|
}
|