| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 24 | 0 | 0% |
| Commands | 0 | 8 | 0 | 0% |
| Section tags | 0 | 8 | 0 | 0% |
What each file covers
Sections
0 shared · 24 only in A · 0 only in B- − CLAUDE.md
- − Project Overview
- − Common Commands
- − Testing
- − Run all tests
- − Run a single test file
- − Run tests with verbose output
- − Development
- − Run the example
- − Analyze code
- − Format code
- − Publishing
- − Check package for publish readiness
- − Publish to pub.dev
- − Architecture
- − Core Components
- − Template System
- − Web/WASM Compatibility
- − Project-Specific Rules
- − PRD Reference
- − Collaboration Boundaries
- − Validation & Planning
- − Key Dependencies
- − Testing Philosophy
Commands
0 shared · 8 only in A · 0 only in B- − dart test
- − dart test test/pico_schema_test.dart
- − dart test --reporter=expanded
- − dart run example/main.dart
- − dart analyze
- − dart format .
- − dart pub publish --dry-run
- − dart pub publish
Section tags
0 shared · 8 only in A · 0 only in B- − test
- − lint-format
- − architecture
- − types
- − dependencies
- − deployment
- − do-not
- − agent-behaviour
Line diff
csells/dotprompt_dart · CLAUDE.md
@@ −1 @@
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
csells/dotprompt_dart · .cursor/rules/validation-planning.mdc
@@ +1 @@
1---
2description:
3globs:
4alwaysApply: true
5---
6Before taking any action in the dotprompt project:
7
81. **Initial Assessment**
9 - Verify understanding of the current state and requirements
10 - Check if all necessary context is available
11 - Only ask for user input if there's a real choice of implementation approaches
12
132. **Planning Phase**
14 - Outline the proposed approach before implementation
15 - List all required steps and dependencies
16 - Identify potential risks or edge cases
17 - Consider alternative solutions only if they significantly differ in approach
18
193. **Validation Steps**
20 - Verify that the proposed solution aligns with:
21 - Official reference documentation (e.g., dotprompt.io/docs)
22 - Library implementation details and best practices
23 - Existing codebase patterns and conventions
24 - Check for any potential conflicts with existing functionality
25 - Ensure all dependencies are properly considered and validated
26
274. **Documentation Check**
28 - Review relevant official documentation
29 - Check if the proposed changes require documentation updates
30 - Ensure all changes will be properly documented
31 - Validate against library-specific documentation
32
335. **Implementation Strategy**
34 - Break down the implementation into clear, manageable steps
35 - Identify which files will be affected
36 - Plan for testing and validation
37 - Consider rollback strategy if needed
38 - Proceed with implementation unless there's a clear reason to wait for user input
39
406. **Communication**
41 - Clearly explain the planned approach
42 - Highlight any assumptions or dependencies
43 - Only ask for clarification if there's a genuine need for user input
44 - Provide reasoning for chosen approach
45 - Proceed with implementation unless explicitly stopped
46
477. **Execution**
48 - Proceed with implementation after validation
49 - Make changes incrementally where possible
50 - Verify each step against reference documentation
51 - Document any deviations from the plan
52 - Only pause for user input if there's a critical decision point
53
@@ −1 +1 @@
1−# CLAUDE.md
1+---
2+description:
3+globs:
4+alwaysApply: true
5+---
6+Before taking any action in the dotprompt project:
27
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
8+1. **Initial Assessment**
9+ - Verify understanding of the current state and requirements
10+ - Check if all necessary context is available
11+ - Only ask for user input if there's a real choice of implementation approaches
412
5−## Project Overview
13+2. **Planning Phase**
14+ - Outline the proposed approach before implementation
15+ - List all required steps and dependencies
16+ - Identify potential risks or edge cases
17+ - Consider alternative solutions only if they significantly differ in approach
618
7−A 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.
19+3. **Validation Steps**
20+ - Verify that the proposed solution aligns with:
21+ - Official reference documentation (e.g., dotprompt.io/docs)
22+ - Library implementation details and best practices
23+ - Existing codebase patterns and conventions
24+ - Check for any potential conflicts with existing functionality
25+ - Ensure all dependencies are properly considered and validated
826
9−This 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).
27+4. **Documentation Check**
28+ - Review relevant official documentation
29+ - Check if the proposed changes require documentation updates
30+ - Ensure all changes will be properly documented
31+ - Validate against library-specific documentation
1032
11−## Common Commands
33+5. **Implementation Strategy**
34+ - Break down the implementation into clear, manageable steps
35+ - Identify which files will be affected
36+ - Plan for testing and validation
37+ - Consider rollback strategy if needed
38+ - Proceed with implementation unless there's a clear reason to wait for user input
1239
13−### Testing
14−```bash
15−# Run all tests
16−dart test
40+6. **Communication**
41+ - Clearly explain the planned approach
42+ - Highlight any assumptions or dependencies
43+ - Only ask for clarification if there's a genuine need for user input
44+ - Provide reasoning for chosen approach
45+ - Proceed with implementation unless explicitly stopped
1746
18−# Run a single test file
19−dart test test/pico_schema_test.dart
20−
21−# Run tests with verbose output
22−dart test --reporter=expanded
23−```
24−
25−### Development
26−```bash
27−# Run the example
28−dart run example/main.dart
29−
30−# Analyze code
31−dart analyze
32−
33−# Format code
34−dart format .
35−```
36−
37−### Publishing
38−```bash
39−# Check package for publish readiness
40−dart pub publish --dry-run
41−
42−# Publish to pub.dev
43−dart pub publish
44−```
45−
46−## Architecture
47−
48−### Core Components
49−
50−1. **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−
57−2. **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−
70−3. **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−
75−4. **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−
82−Uses [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−
86−Version 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−
118−Tests 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).
47+7. **Execution**
48+ - Proceed with implementation after validation
49+ - Make changes incrementally where possible
50+ - Verify each step against reference documentation
51+ - Document any deviations from the plan
52+ - Only pause for user input if there's a critical decision point
11953
