feat: improve validation error messages with actionable guidance

[sgriffiths]

Summary

Resolves the conflict from PR #27 by @aicontentcreate2023-star (Chu Julung) and applies the enhanced error message pattern to the current codebase. Closes #24.

• All validation errors now show actual type received vs expected (e.g., got int)
• Field paths included in every error (e.g., tasks.my_task.input)
• YAML examples provided for missing/incorrect fields
• Available options listed when tool/task references fail
• Array indices shown for collection errors (e.g., tools[1].id)
• Missing section detection with full add-it-like-this guidance
• Enhanced messages applied to all validators including multi-step task validation added since PR feat: improve validation error messages for invalid YAML specs #27

Before/After

# Before
ValueError: agent.name must be a string

# After  
ValueError: Field 'agent.name' must be a string, got int.
Example: agent:
  name: "my-agent"

# Before
ValueError: task my_task references non-existent tool 'web_search'

# After
ValueError: tasks.my_task references non-existent tool 'web_search'.
Available tools: 'file_reader', 'calculator'. Check your 'tools' section.

Test plan

• 25 new tests in tests/test_validation_errors.py — all passing
• All 101 existing tests still pass (100 passed, 1 skipped)
• Ruff lint clean
• No breaking changes — still raises ValueError

Co-authored-by: Chu Julung chujulung@ChudeMacBook-Air.local

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
open-agent-spec	Ready	Preview, Comment	Mar 11, 2026 11:16pm