AGENTS.md

1# AGENTS.md
2 
3Guidance for working with the AI Workflow Builder package.
4 
5## Prompt Development
6 
7Use the `PromptBuilder` utility for all LLM prompts. See `src/prompts/README.md`
8for detailed documentation.
9 
10```typescript
11import { prompt } from '@/prompts/builder';
12 
13const systemPrompt = prompt()
14  .section('role', 'You are an assistant')
15  .sectionIf(hasContext, 'context', () => buildContext())
16  .build();
17```
18 
19Key methods:
20- `section(name, content)` - Always included
21- `sectionIf(condition, name, content)` - Conditionally included
22- `examples(name, items, formatter)` - Formatted example list
23- `build()` - Returns the final prompt string
24 
25## Workflow Examples in Prompts
26 
27When including workflow examples in prompts, use Mermaid flowcharts instead of
28raw JSON. Generate Mermaid from workflow JSON using:
29 
30```bash
31pnpm workflow:mermaid path/to/workflow.json
32```
33 
34This outputs a markdown file with a Mermaid diagram. The diagram is more
35readable for the LLM and uses fewer tokens than JSON.
36 
37Options:
38- `--no-node-name` - Exclude node names
39- `--no-node-type` - Exclude node type comments
40- `--node-params` - Include node parameters
41 
42## Evaluations
43 
44Before modifying evaluations, judgement criteria, or scoring logic, read
45`evaluations/README.md` for the evaluation framework architecture and guidelines.