CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7A Dart package for parsing `.prompt` files for LLM interactions. Based on [Google's dotprompt specification](https://google.github.io/dotprompt/getting-started/), this implementation converts Pico Schema to JSON Schema, provides schema validation, template rendering with Handlebars/Mustache, and model configuration management.
8 
9This package does NOT execute prompts itself - it parses and prepares them for execution by other libraries like [dartantic_ai](https://pub.dev/packages/dartantic_ai).
10 
11## Common Commands
12 
13### Testing
14```bash
15# Run all tests
16dart test
17 
18# Run a single test file
19dart test test/pico_schema_test.dart
20 
21# Run tests with verbose output
22dart test --reporter=expanded
23```
24 
25### Development
26```bash
27# Run the example
28dart run example/main.dart
29 
30# Analyze code
31dart analyze
32 
33# Format code
34dart format .
35```
36 
37### Publishing
38```bash
39# Check package for publish readiness
40dart pub publish --dry-run
41 
42# Publish to pub.dev
43dart pub publish
44```
45 
46## Architecture
47 
48### Core Components
49 
501. **DotPrompt** ([lib/src/dot_prompt.dart](lib/src/dot_prompt.dart)) - Main entry point
51   - Parses .prompt files with YAML front-matter and Handlebars templates
52   - Factory constructor `DotPrompt(String)` for string content
53   - Static method `DotPrompt.stream(Stream<List<int>>, {name, defaults})` for loading from streams (required for web/wasm compatibility)
54   - `render(Map<String, dynamic>)` method validates input against schema and renders template
55   - Merges default values with input before validation
56 
572. **PicoSchema** ([lib/src/pico_schema.dart](lib/src/pico_schema.dart)) - Schema conversion engine
58   - Detects schema type (JSON Schema vs Pico Schema) using `schemaType()`
59   - Top-level `type` property triggers JSON Schema mode (short-circuits Pico Schema parsing)
60   - Mixed schemas throw `FormatException`
61   - Expands Pico Schema shorthand into valid JSON Schema
62   - 100+ tests ensure spec compliance
63   - Key features:
64     - Optional fields: `name?: string`
65     - Type annotations: `settings(object)`, `tags(array)`
66     - Enums: `theme: [light, dark]` or `theme(enum): [light, dark]`
67     - Wildcards: `(*): any` for additionalProperties
68     - Inline descriptions: `name: string, The user's name`
69 
703. **DotPromptFrontMatter** ([lib/src/dot_prompt_front_matter.dart](lib/src/dot_prompt_front_matter.dart))
71   - Parses YAML front-matter between `---` delimiters
72   - Includes model config, input/output schemas, and custom extensions
73   - Supports namespaced keys (e.g., `myext.temperature`)
74 
754. **InputOutputConfig** ([lib/src/input_output_config.dart](lib/src/input_output_config.dart))
76   - Manages input/output schemas and defaults
77   - Creates `JsonSchema` objects from Pico Schema or JSON Schema
78   - Stores default values for input validation
79 
80### Template System
81 
82Uses [mustache_template](https://pub.dev/packages/mustache_template) package for template expansion. NOT fully spec-compliant with Google's Handlebars implementation - see README.md "Handlebar Implementation Shortcomings" section for known limitations.
83 
84### Web/WASM Compatibility
85 
86Version 0.3.0+ replaced `DotPrompt.file(filename)` with `DotPrompt.stream(bytes, name: filename)` for web/wasm compatibility. Use `File(filename).openRead()` to create the stream for file system sources.
87 
88## Project-Specific Rules
89 
90### PRD Reference
91- Read [PRD.md](PRD.md) at the start of each session
92- Reference PRD when implementing features
93- Update PRD if implementation requires requirement changes
94- Document changes to core functionality, API design, architecture, dependencies, or user stories
95 
96### Collaboration Boundaries
97- Only implement what is explicitly requested
98- Present ideas as suggestions ("I have an idea...") without implementing
99- Ask for clarification if scope is unclear
100- Wait for explicit approval before actions beyond immediate request
101 
102### Validation & Planning
103- Verify understanding before implementation
104- Validate against [official dotprompt docs](https://google.github.io/dotprompt/)
105- Check library implementation details and best practices
106- Ensure changes align with existing codebase patterns
107 
108## Key Dependencies
109 
110- `json_schema`: ^5.2.1 - JSON Schema validation
111- `yaml`: ^3.1.2 - YAML front-matter parsing
112- `mustache_template`: ^2.0.0 - Template expansion
113- `path`: ^1.8.0 - Path manipulation
114- `collection`: ^1.19.1 - Collection utilities
115 
116## Testing Philosophy
117 
118Tests are comprehensive with 100+ tests focused on Pico Schema conversion. Tests should be silent on success and report failures via `expect()`. No print statements except for diagnostics (which should be removed before commit).
119